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Preface 


If you bought your Apple //c in order to do all sorts of strange things to it: 
POKE around in it, PEEK inside it, CALL subroutines, RUN programs, and 
soon...If you thrill in making a computer do things that its designers never 
imagined .. . If you write and debug programs for fun . . . If you have an Apple 
bumper sticker on your car . . . This book is for you! 

In this book, we're going to explore all the important software nooks and 
crannies in the //c and see how to exploit the power that they hold. You will 
be expected to be proficient in the Applesoft BASIC language; an understand- 
ing of 65C@2 assembly language will also be invaluable. 

Some of the major topics that will be covered are as follows: 


@ The 65C0@2 microprocessor that controls the //c. This will include a dis- 
cussion of 65C@2 instructions, addressing modes, I/O handling, and inter- 
rupt handling. 

@ The //c system monitor commands, the structure of the Applesoft lan- 
guage, and the internal structure of ProDOS. 

@ How the //c handles character input and output. This includes a discus- 
sion of keyboard input and the various video display modes supported 
by the //c (text, graphics, and double-width graphics). 

@ Memory management techniques. 

@ How to control the speaker, mouse, and game controller. 

@ How to use the //c’s two built-in serial ports for communication with 
printers and modems. 


After you have read this book, you will know absolutely everything there is 
to know about how the //c interacts with the outside world and how it pro- 
cesses information. (Well, almost everything.) Descriptions of all the “soft 
switches’ that the //c uses to control its hardware environment will be pre- 
sented, as will examples of how to use the //c’s I/O memory locations. Fur- 
thermore, many of the more important subroutines contained in the //c’s 
ROM area will be analyzed and explained. 

Here are some of the more interesting programming examples that will be 
presented in this book: 


@ How to speed up the auto-repeat rate of the cursor (using software tech- 
niques only). 

® How to run two Applesoft programs concurrently (one in main memory 
and the other in auxiliary memory). 

e How to read mouse input using 65C@2 interrupt techniques. 

® How to read and write specific blocks on a ProDOS-formatted diskette. 

@ How to use the keyboard ‘‘type-ahead”’ feature. 


Complete and commented source listings for these programs and several 
others are included in the text. They are also available in machine-readable 
form on an optional diskette. 


xiii 
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I hope that you enjoy reading this book as much as I enjoyed writing it. 
You'll find it a useful reference and an invaluable source of inspiration for 
the development of your own software. 

My thanks to Rich Williams and Apple Computer, Inc. in Cupertino for 
helping me to decode the meaning of some of the more obscure code in the 
//c’s ROM. Rich should know—he wrote most of it. 


Gary B. Little 
Vancouver, British Columbia, Canada 


March 1985 
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An Introduction to Apple 
and the Apple //c 


The Apple //c is the newest member of Apple Computer Inc.’s highly popular 
Apple II family of computers. The other members of this family are the original 
Apple II (1977), the Apple II Plus (1979), and the Apple //e (1983). 


In this book we will be taking an advanced “inside’’ look at the Apple //c 
itself. Keep in mind, however, that much of what will be said will also apply 
to its three predecessors because Apple has made a substantial effort to 
maintain a high degree of compatibility with other members of the Apple II 
family. We will be concentrating on the //c’s built-in language and operating 
system (Applesoft and the system monitor) and the ProDOS disk operating 
system; other languages and operating systems will be mentioned only briefly. 


A Condensed History of Apple Computer, Inc. 


Before we begin our detailed examination of the Apple //c, let’s take a brief 
look at the history of Apple, the company. This history will reveal how the 
original Apple II slowly evolved into the Apple //c in 1984 and will serve to 
explain much of the rationale behind the design of the //c. 


1976 


In the beginning, Apple was made up of just two individuals: Stephen 
Wozniak (““Woz’’) and Steven Jobs. Woz provided the hardware and software 
expertise and almost single-handedly designed the company’s first two com- 
puters, the Apple I and the Apple II (he had the help of Rod Holt who designed 
the Apple II’s power supply). A patent application was subsequently filed with 
respect to the Apple II on April 11, 1977, and U.S. patent #4,136,359 was 
eventually issued in early 1979. Jobs was largely responsible for marketing 
and raising financing, and it was he who came up with the “Apple” name 
(Jobs was apparently thinking of a job that he had recently had in an Oregon 
orchard). In the early going, both partners were still working for other com- 
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puter companies in California's Silicon Valley: Jobs with Atari and Woz with 
Hewlett-Packard. Fortunately for Apple, Hewlett-Packard was not interested 
in Woz’s design for a personal computer and gave him a release so that he 
could deal with it as he saw fit. 


The Apple I was designed to be sold to and used by hobbyists only; in all, 
only about 175 were sold. The Apple II, however, was designed with a much 
larger market in mind (although Woz claims he simply wanted to build a 
computer with which he could play Atari’s “Breakout” game). That market 
quickly materialized as a result of the startling combination (for 1977) of 
excellent hardware, attractive packaging, and the availability of informative 
technical reference material. 


Woz decided to use the MOS Technology 6502 microprocessor to control 
the Apple II. This decision was dictated not by the 6502's reliability, powerful 
instruction set, or any other design characteristic, but rather by its price. 
Whereas other microprocessors were selling for hundreds of dollars in 1976 
and were difficult to find, the 6502 was readily available and it cost only 
about twenty dollars. The //c uses the newer 65C@2 microprocessor, but it 
recognizes all the instructions that the original 6502 uses and supports a few 
new ones as well. 


With assistance from Allen Baum, Woz wrote all the software for the orig- 
inal Apple II that was stored in its read-only memory (ROM). This included 
a version of the BASIC programming language called Integer BASIC (which 
can't handle decimal numbers but is great for games), a system monitor for 
debugging and for handling fundamental input/output operations, a set of 
mathematical subroutines, a mini-assembler for entering programs in assem- 
bly language, and ‘Sweet 16,” a software-simulated 16-bit microprocessor 
(Woz was way ahead of his time). 


To raise a little money for their fledgling venture, Woz sold his Hewlett- 
Packard pocket calculator and Jobs sold his Volkswagen bus. Overhead expenses 
were cut to the bare minimum by setting up operation in the garage of Jobs’ 
parents. As 1977 rolled around, however, it became clear that more money, a 
lot more money, was going to be needed. 


1977 


Since Jobs was the partner responsible for marketing the Apple II, it was 
he who began searching for venture capital. That search eventually led him 
to Mike Markkula, a former marketing manager at Intel, an integrated-circuit 
designing company. Markkula, Jobs, and Wozniak quickly struck a deal whereby 
Markkula agreed to put a quarter of a million dollars into Apple in exchange 
for an equal partnership interest. He then proceeded to use his expertise to 
line up bank financing and additional capital funding. Apple was then finally 
ready for the mass market! 
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The Apple II was formally announced for sale at the first annual West 
Coast Computer Faire in early 1977 and it was an instant success. The main 
reasons for its early success were that it was easily expandable (more memory 
could easily be added to it and eight slots were available for peripheral devices 
when they became available), it had a full-size keyboard, and it had color 
graphics. And, yes, it looked great! 


Not that there weren't any problems, however. For example, lower case 
characters could not be produced by the keyboard and the video display was 
only forty columns wide. These shortcomings officially persisted until the 
introduction of the Apple //e in 1983, although several other sources of upper- 
and lowercase keyboards and 80-column boards did pop up in the interim. 


One software problem had to be remedied quickly. Integer BASIC did not 
support decimal (floating-point) numbers or functions, and so business and 
scientific use of the Apple II was necessarily limited. Apple began to take steps 
to remedy this in the summer of 1977 when it negotiated the purchase of 
about ten thousand lines of program source code for a floating-point version 
of BASIC from Microsoft Corporation. This code was written in 6502 assembly 
language and so could be readily adapted to run on the Apple II. 


By this time Apple had a few employees, one of which was a young pro- 
grammer by the name of Randy Wigginton. Wigginton reworked the Microsoft 
source code and came out witha preliminary version of a floating-point BASIC 
that would run on the Apple II. This version was called ‘‘Applesoft—Extended 
Precision Floating Point BASIC Language’ and was released in October 1977. 
Further work was required to polish Applesoft into a final product, and this 
was done during the winter of 1977. 


1978 


The final version of Applesoft, Applesoft ][, was finally released in May 1978; 
this same version, with some minor changes, is still in use today on the Apple 
//c. It was first available on cassette tape only, but was later provided in ROM 
on a card that could be plugged into a slot on the Apple II; it eventually 
replaced Integer BASIC on the motherboard when the Apple II Plus was 
released in 1979. 


The most important new product released in 1978 was probably the Disk 
II disk drive and controller card peripherals that are now built in to the Apple 
//c. The disk drive revolutionized the software business because for the first 
time it was feasible to develop sophisticated programs that could be easily 
loaded and that could quickly and reliably access large data bases. Until the 
disk drive was released, all programs had to be saved to and loaded from 
cassette tape, which was invariably an exercise in frustration. Many a cottage 
software business started up after the disk drive became available, and in a 
short time hundreds of commercial software products were being developed 
for the Apple II. 
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The Disk II was controlled by a program called the Disk Operating System 
(DOS), first written by Bob Shepardson and later substantially modified by 
Randy Wigginton, J. R. Huston, and Rick Auricchio. DOS has undergone 
several revisions throughout the years and the current version is DOS 3.3. 
This version still works with the Apple //c, although it has been superseded 
by a new DOS called ProDOS. 


1979 


Sales really ballooned for Apple in 1979. Apple was able to increase sales 
by a total of forty million dollars (!) over the previous year, to a total of forty- 
eight million dollars. By this time, the Apple II was selling not only because 
it was an excellent hardware package but also because an ever-increasing 
supply of software was available that could be run on it. One important piece 
of software, VisiCalc, the very first financial spreadsheet program, is reputed 
to have been directly responsible for stimulating the purchase of tens of 
thousands of Apple II computers. 


The Apple II underwent minor surgery in 1979 and came out of it with a 
new name: Apple II Plus. The Apple II Plus is essentially the same as an Apple 
II, except that its ROM chips contain Applesoft ][ rather than Integer BASIC 
and its system monitor supports more powerful screen-editing commands 
and the ability to automatically run a program from diskette whenever the 
power is turned on. At the same time, a couple of handy debugging commands 
(step and trace) were taken out of the system monitor, but they were not 
missed by many users. The modifications to the system monitor were written 
by John Arkley. 


Apple announced its Pascal Operating System in 1979 as well. Because 
Pascal requires a huge amount of memory in which to operate, Apple also 
released a new peripheral card, called a language card, at the same time. The 
language card effectively added another 16K of memory to the Apple II, which 
could “replace” the Applesoft ROMs when Pascal was being used. The lan- 
guage card was plugged into slot #0 of the Apple IT but in the //c it is simulated 
in the memory chips on the motherboard. These different implementations, 
however, are transparent to the user. 


1980-1982 


Apple’s sales continued to explode in the early eighties: $117 million in 
1980, $334.8 million in 1981, and $583.1 million in 1982! Most of these sales 
were generated by the Apple II Plus, which eventually set a record for monthly 
sales in December 1982. 


The infamous Apple /// was released in 1980. For several reasons, notably 
its early unreliability and high price, it never established a significant market 
presence even though a modified version (known as the Apple /// Plus) was 
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still being produced as late as 1984. It comes with an Apple II emulation 
mode that allows it to run most, but not all, of the software that runs on the 
Apple II. 


In the winter of 1980-81, Apple made a public offering of stock, which was 
quickly snapped up. The proceeds were largely directed into intensive (and 
expensive) research and development projects. We'll see in a moment what 
those projects led to. 


If imitation is the sincerest form of flattery, then Apple must surely be 
blushing. Since about 1980, tens of thousands of unofficial Apple II “clones” 
(euphemistically called ““compatibles’’) have been manufactured, mostly by 
Taiwanese concerns. To achieve absolute compatibility with the Apple II, 
most of these clones contain ROMs that are direct copies of the Applesoft and 
system monitor ROMs. Not surprisingly, Apple considers this to be highly 
improper and has successfully instituted legal proceedings in the United 
States and many other countries against several manufacturers in order to 
protect its copyrights and patent rights. The importation of Apple II clones 
to the United States has also been reduced because Apple has registered its 
copyrights with U.S. Customs. The Customs authorities have the power to 
confiscate shipments of products that violate Apple's copyrights. 


1983 


At Apple’s Annual General Meeting on January 19, 1983, two major 
announcements were made. First, the Lisa computer was announced, a com- 
puter that was immediately recognized as a technological and innovative 
triumph because of its ease of use and excellent operating system. Its retail 
price, however, was initially too high for it to sell in the quantities that Apple 
would have liked. Subsequent price reductions, coupled with increasing avail- 
ability of software, has helped to remedy this problem. 


The second major announcement was the introduction of the successor to 
the Apple II Plus, the Apple //e. The Apple //e was carefully designed to 
maintain as high a degree of compatibility with the Apple II Plus as possible 
so that the thousands of software packages developed for the Apple II Plus 
would not have to be rewritten. Several new features were added to the //e, 
however, that make it a significantly different computer: built-in support for 
an 80-column display, an upper- and lowercase keyboard, self-testing subrou- 
tines, and enhanced editing capabilities. 


In addition, Apple significantly simplified the construction of the //e by 
reducing the number of integrated circuits on the motherboard from 109 on 
the Apple II Plus to only 31! It did this by designing two special integrated 
circuits to replace many of the discrete components used on the II Plus. 


The manager of the team that designed the Apple //e was Peter Quinn. The 
hardware was designed by Walt Broedner and most of the modifications to 
the old system monitor were made by Rick Auricchio and Bryan Stearns. 
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There was also a major change at the managerial level at Apple in 1983. On 
April 8, Apple announced that Mike Markkula had resigned as President and 
that John Sculley had been named to succeed him. Sculley was formerly 
president of Pepsi-Cola and it is reported that his salary is in excess of one 
million dollars per year. 


1984 


At its January 24, 1984, Annual General Meeting Apple announced the 
Macintosh computer (‘““Mac’’), a scaled-down version of Lisa. Mac undoubt- 
edly represents another mass-market best seller for Apple because it is easy 
to use and it is priced affordably. Within a month of its release, at least two 
Mac-specific magazines and several books had been published. This is remi- 
niscent of what happened in 1979 when sales of the Apple II began to sky- 
rocket. 


For users of Apple II computers, there was one major announcement at the 
Annual General Meeting: the release of a successor to DOS 3.3 called ProDOS. 
This disk operating system is significantly different from, but upwardly com- 
patible with, DOS 3.3. Most Applesoft programs, when transferred to ProDOS- 
formatted diskettes, will run without modification. The main advantages of 
ProDOS are that it is faster, it is easier for programmers to use, it supports a 
directory structure that is more convenient for use with larger-capacity dis- 
kettes or hard disks, and its disk format can be read by the Apple ///. 


On April 24, 1984, Apple formally introduced the portable Apple //c. In 
keeping with Apple tradition, the //c is compatible with most software designed 
for its predecessor, the Apple //e. However, the //c actually represents a radical 
departure from the Apple II norm because of the way the hardware has been 
packaged. For example, the peripheral expansion slots on the //e are gone and 
have been replaced by built-in interfaces and a built-in disk drive. This was 
done primarily to reduce the size of the unit to that of a true portable, and 
also to make the //c appeal more to the large “plug ’n run” class of users. 
Furthermore, the //c simply looks different than any of the earlier Apple II 
computers. 


The //c is a wonder of computer miniaturization. Not counting the sixteen 
RAM chips that provide the //c with 128K of memory, there are only twenty- 
one integrated circuits (ICs) used in the system. Several of these ICs are custom 
large-scale-integration (LSI) chips that perform tasks that are normally han- 
dled by several discrete ICs when conventional technology is used. 


The manager of the //c design team was the same Peter Quinn who was in 
charge of the //e project. The //c’s firmware was written by Ernie Beernink, 
Rich Williams, and James Huston; if you ever forget their names, press 
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[control-RESET] right after you turn on the //c (before the disk has a chance 
to boot up), and then type in and run the following short Applesoft program: 


108 IN# S: INPUT A$: PRINT A$ 


Surprise, surprise! 


Hardware and the Apple //c 


Although this book is primarily concerned with software, let’s begin by 
taking a quick look at the hardware that makes up the Apple //c. 


The keyboard is laid out in the standard QWERTY arrangement and con- 
tains all of the keys you would find on a standard typewriter plus a few extra 
special ones to boot. Just above the keyboard are the reset button, the 80/40 
switch, and the keyboard switch. The keyboard and these special switches 
will be described in detail in Chapter 6. 


On the left side of the //c you will find the volume control wheel for the 
speaker and the speaker headphone jack. You can’t see the speaker because 
it’s under the hood. In Chapter 9 we will see how it can be used to generate 
music. 


On the other side of the //c is the built-in disk drive. This drive can read 
diskettes formatted on all previous Apple IT models. 


We won't encourage you to take the //c apart to see the electronic circuitry 
lurking beneath the surface since this is frowned on by the warranty people 
at Apple. If you did, however, you would see the various integrated circuits 
that make up the //c, including the 65C@2 microprocessor that controls every- 
thing, the two 6551 serial communications adapters, and the RAM and ROM 
memory chips. 

The //c can be interfaced to the “‘real world”’ through one of seven connectors 
that are located on its back panel (see Figure 1-1): 


@ The mouse/game connector: This is where the Apple Mouse or a joystick 
can be connected. We will be examining it in Chapter 10. 


@ The modem port (serial port 2): A modem is a device that allows you to 
communicate with other computers over standard telephone lines. See 
Chapter 11. 


@ The video expansion connector: This connector allows the //c to be con- 
nected to any of several display options, including RGB (red-green-blue) 
displays, flat-panel liquid-crystal displays, and ordinary black and white 
or color television sets. 

@ The video monitor connector. 


@ The external disk drive connector: For those who can’t survive with just 
one drive. 
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Figure 1-1. Back panel of the Apple //c. 


@ The printer port (serial port 1): A printer will undoubtedly be the first 
peripheral that you add to your //c. See Chapter 11. 


@ The power connector: You can’t do much without it! 


Previous members of the Apple II family have several expansion slots that 
can be used to hold interface cards that control external devices. The //c has 
no such slots, but its built-in interfaces and supporting software have been 
carefully designed so that they can be controlled by the same commands that 
would be used on a slot-based Apple II. The only difference is a semantical 
one: you refer to “‘port’’ numbers on the //c and to “slot” numbers on the 
Apple //e, Apple II Plus, and Apple II. The numbers assigned to each port on 
the //c are shown in Table 1-1. 

So much for the //c’s hardware! 


Learning the Fundamentals 


Most of the readers of this book are expected to be intermediate to advanced 
programmers who need no explanation of fundamental concepts such as 
numbering systems, bits and bytes, pointers, vectors, assembly language, and 
how to load and run programs. 
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Table 1-1. Port assignments on the Apple //c. 


Port 
Number Description 
) Standard keyboard and video I/O (see Chapters 6 and 7) 
1 Serial interface for printer (see Chapter 11) 
2 Serial interface for modem (see Chapter 11) 
3 80-column video display (see Chapter 7) 
4 Mouse interface (see Chapter 10) 
6 Internal disk drive interface (see Chapter 5) 
7 


External disk drive interface (see Chapter 5) 


If you feel a little uncomfortable with any of these concepts, then you should 
first read Appendix V (‘For Beginners Only’’) before attempting to tackle the 
rest of this book. You will probably also feel more comfortable if you read an 
introductory book on computer systems first. 


What Won’t Be Covered 


There are a few topics that will not be discussed at length in this book. 
Integer BASIC, the BASIC that was built into the first several thousand Apple 
II’s, will not be discussed because it is rarely used anymore and is fast becom- 
ing obsolete. In fact, the ProDOS disk operating system does not allow Integer 
BASIC programs to be run at all. 


The only high-level language that will be discussed at length will be Apple- 
soft. For more information on Apple Pascal, Fortran, or Logo, you will have 
to consult other texts. 


Using the Optional Diskette 


This book can be purchased either with or without a ProDOS- formatted 
program diskette, or the diskette can be purchased separately. The diskette 
contains all the programs that are presented as examples in the following 
chapters and will allow you to quickly load a program into memory, or modify 
a program, without having to endure the pleasure of typing it in from scratch. 


The files on the diskette are either Applesoft programs (marked by “BAS” 
when you CATALOG the diskette), text files (marked by “TXT”), or binary 
programs (marked by ““BIN”). 


The text files on the diskette are the source-code listings for the binary 
programs and are in the format expected by the Merlin Pro assembler (which 
is available from Roger Wagner Publishing, Inc., 10761 Woodside Avenue, 
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Suite E, Santee, California). Most other assemblers are also able to read these 
text files. Keep in mind, however, that the source-code formats used by dif- 
ferent assemblers do vary and it may be necessary to modify a source code 
file to take into account any such differences before the file can be properly 
assembled. 


The Applesoft programs and binary programs can usually be run by using 
the standard RUN and BRUN commands, respectively, or the ProDOS “‘intel- 
ligent RUN command”, “—”’ (a dash), which automatically checks the file type 
and will RUN an Applesoft program or BRUN a binary program. Some of the 
binary programs, however, are designed to be called from an Applesoft pro- 
gram only and should simply be loaded into memory using the BLOAD 
command. Such exceptions will be noted in the discussions that relate to 
these programs in this book. 


Further Reading for Chapter 1 


Historical background ... 


“Photograph of AppleI’’, Apple Orchard, April 1983, front cover. The original 
Apple product. 


A.L. Taylor III, “Striking it Rich”, Time, February 15, 1982, pp. 42-47. Apple 
makes the front cover of Time. 


D. Garr, Woz: The Prodigal Son of Silicon Valley, Avon Books, 1984. An in- 
depth review of the history of Apple. 


P. Freiberger and M. Swaine, Fire in the Valley: The Making of the Personal 
Computer, Osborne/McGraw-Hill, 1984. 


M. Moritz, The Little Kingdom: The Private Story of Apple Computer, 
Morrow, 1984. 


P. Lopiccola, “Core of a New Apple’, Popular Computing, March 1983, pp. 
114-117. How the Apple II Plus was transformed into the //c’s predecessor, 
the Apple //e. 


J. Markoff, ‘‘The Apple IIc Personal Computer’, Byte, May 1984, pp. 276- 
284. Refer to this article for pictures of the inside of the //c and a good 
overview of the //c’s hardware. 


Standard reference work ... 


The Apple lic Reference Manual, Volumes 1 and 2, Apple Computer, Inc., 1984. 
Includes detailed information on the hardware and software that makes 
up the Apple //c. Source code for the //c system monitor is included. 


The 65CQ2 
Microprocessor 


The “brains” of every microcomputer are represented by a complex inte- 
grated circuit called a microprocessor that controls the operation of the 
system as a whole. The microprocessor used in the //c is called a 65C@2. 


The 65C@2 is closely related to the 6502 microprocessor that is used in the 
Apple //e, Apple II Plus, and Apple II. In fact, all programming instructions 
supported by the 6502 are also supported by the 65C@2. This is fortunate since 
it means that no translation of specific 6502 instructions need be performed 
before the program can be executed by the 65C@2 microprocessor. (This does 
not mean, of course, that any program written for the 6502-based Apple 
systems will run on the //c. Ifthe program accesses subroutines or I/O locations 
that are not present on the //c, then it will obviously not run properly and 
will have to be rewritten.) 


It’s not a two-way street, however. Assembly-language programs written 
specifically for the 65C@2 may have to be partially translated before they will 
run on a computer using the 6502. This is because the 65C@2 used on the //c 
supports ten new instructions and some new memory addressing techniques 
that the 6502 does not. If the 6502 is asked to interpret these new instructions, 
it will fail miserably. 


In this chapter we will be taking special note of these new instructions. If 
you are writing software that must run on either a 65C@2- or a 6502-based 
Apple, then you must not use them. 


By the way, the “C”’ in 65C@2 stands for CMOS, an acronym for Comple- 
mentary Metal Oxide Semiconductor. This is the name for the process used 
to manufacture the transistors that form the 65CQ2 integrated circuit. ACMOS 
integrated circuit consumes far less power than a functionally identical circuit 
built using conventional technology. It will run cooler and can be operated 
by a smaller power supply. These are important factors when you want to 
design a small, portable, computer like the //c. 


The 65C@2 is an example of what is usually called an ‘8-bit”’ microprocessor. 
These types of microprocessors can handle data only one byte (8 bits) at a 
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time and they typically use 16 lines to address memory. Since each of these 
lines can be on or off, the 65C@2 is capable of addressing 65,536 (2% 16) memory 
locations at any given time. (Since one ‘‘K”’ of memory is equal to 1,024 bytes, 
this represents a 64K" memory space.) Contrast this with the newer wave 
of 16-bit microprocessors that can manipulate two bytes of data at once and 
have typical address spaces of one megabyte or more. 


While the 65C@2 is operating, it is continuously interpreting a stream of 
bytes in order to determine what it should do next. The bytes in this stream 
are controlled by the computer program that is being executed. This program 
contains instructions that enable the 65C@2 to perform data transfers, input/ 
output operations, logical operations, simple arithmetic, and other funda- 
mental control operations. 


In this chapter, we will take a brief look at the 65C0@2 instruction set and 
internal registers and describe how the 65C@2 has been implemented on the 
/ic. Note, however, that the purpose of this chapter is not to teach you 65C02 
assembly-language programming, but rather to review some of the more 
important principles relating to the 65C02 microprocessor. Consult the ref- 
erences at the end of the chapter for a list of books that are available to teach 
you the art of programming the 65CQ2. 


Important 65C02 Concepts 


The 65C@2 forms only one part of a microcomputer system such as the //c. 
The other important parts are the system memory (RAM and ROM) and the 
system input/output (I/O) devices. It is the 65C02, however, that is in charge 
of controlling both the accessing of memory and the passing of data to and 
from the I/O devices. 


The 65C@2 is told how and when to perform its chores by a series of instruc- 
tions that it is constantly interpreting. These instructions will be discussed 
in the next section. In brief, they cause the 65C@2 to perform a variety of data- 
manipulation tasks using a set of six internal registers that will be discussed 
below in the section entitled ‘‘65C@2 Registers.” 


Zero Page and the Stack 


This is a convenient time to introduce you to two rather important areas 
of memory that are used in special ways by the 65C02 microprocessor: zero 
page and the stack. 


Each 256 bytes of memory that starts at an address that is an integer 
multiple of $100 (256), that is, $0000, $0100, $0200, $300, ..., $FFOQ is called 
a ‘‘page’ of memory. For example, the area of memory from $BFQ0@ through 
$BFFF is referred to as page $BF. Zero page, the page of memory from 
$0000 ... $00FF, is treated in a special way by the 65C@2. Generally speaking, 
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whenever the address on which a 65C@2 instruction acts is contained in zero 
page, the highest two hexadecimal digits of the address do not have to be 
specified (since they are always zero by definition). This not only reduces the 
size of the program, it also allows the program to be executed more quickly. 
No wonder, then, that zero page is prime real estate as far as the 65CQ@2 is 
concerned. 


Page one of memory ($100 ...$1FF) holds the 65C@2 stack. The stack is 
used as a temporary data area by the 65C@2 and several instructions can be 
used to implicitly read data from it or store data to it. These instructions are 
executed very quickly because they automatically calculate where to store 
the data or where to read it from by examining a special internal 65C@2 “‘stack 
pointer’ register. This register always points to the next free position avail- 
able in the stack. When a byte is stored on the stack, it is stored at the position 
within page one given by the stack pointer and then the stack pointer is 
decremented by one. When a byte is removed from the stack, the stack pointer 
is incremented by one and then the byte is taken from the position within 
page one pointed to by the stack pointer. 


We will be discussing the stack pointer, and other registers, in greater detail 
below. 


65CQ2 Instruction Set 


There are 66 general types of instructions that the 65C@2 is capable of 
executing; they are listed in Table 2-1. These instructions include all 56 
instructions supported by the standard 6502 microprocessor as well as 10 
new ones used by the 65C@2 only. The new instructions are marked with an 
asterisk in Table 2-1. 


(The //c uses the version of the 65C02 produced by NCR Corporation. Another 
version, produced by Rockwell International Corporation, supports all of the 
NCR instructions and four additional ones called SMB (set memory bit), RMB 
(reset memory bit), BBS (branch on bit set), and BBR (branch on bit reset). 
You cannot use these instructions on the //c.) 


Each instruction is actually a binary number that is interpreted by the 
65CQ2 but it is usually represented by a three-character mnemonic name that 
is easier to remember. These mnemonics are used whenever an assembly- 
language program is being developed. The assembler that is used takes care 
of translating them into the corresponding binary numbers (the “machine 
language ’) that the 65C@2 can execute directly. 


The 65C@2 instructions can be used to perform a wide variety of functions. 
For example, they can be used to pass data between two registers or between 
registers and memory, to perform simple arithmetic, to increment and dec- 
rement index registers and memory locations, to pass data between registers 
and the stack, to perform logical functions, and so on. Figure 2-1 illustrates, 
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in a general way, how each of the 65C@2’s instructions affect memory and the 
65CO@2 registers. 


As you might expect, it takes a finite period of time for any particular 
instruction to be executed by the 65C@2. The time required to execute one 
instruction, however, is not necessarily the same as the time required to 


Table 2-1. 65C02 instruction set mnemonics in alphabetical order. 


ADC Add to accumulator LDX Load X register 
AND “And” with accumulator LDY Load Y register 
ASL Arithmetic bit-shift left LSR_ Logical bit-shift right 
BCC Branch on carry clear NOP No operation 
BCS Branch on carry set UT) os 
BEQ Branch on vesult zero ORA “Or’ with accumulator 
BIT Test bits PHA Push accumulator on stack 
BMI Branch on result minus PHP Push status on stack 
BNE Branch on result not zero *PHX Push X register on stack 
BPL Branch on result plus *PHY Push Y register on stack 
*BRA Branch relative always PLA Pull accumulator from stack 
BRK Software interrupt PLP Pull status from stack 
BVC Branch on overflow clear *PLX Pull X register from stack 
BVS_ Branch on overflow set *PLY Pull Y register from stack 
CLC Clear carry flag ROL Rotate left through carry 
CLD Clear decimal mode flag ROR Rotate right through carry 
CLI Clear interrupt disable flag RTI Return from interrupt 
CLV Clear overflow flag RTS. Return from subroutine 
CMP Compare with accumulator 
CPX Compare with X register SBC Subtract from accumulator 
CPY Compare with Y register SEC Set carry flag 
*DEA Decrement accumulator SED Set decimal mode flag 
DEC Decrement memory by one SEI Set interrupt disable flag 
DEX Decrement X register by one STA Store accumulator 
DEY Decrement Y register by one STX Store Xr egister 
STY Store Y register 
EOR “Exclusive-or’’ with *STZ Store zero in memory 
accumulator TAX Transfer accumulator to X 
*INA Increment accumulator TAY Transfer accumulator to Y 
INC Increment memory by one *TRB Test and Reset with A 
INX Increment X register byone *TSB_ Test and Set withA 
INY Increment Y register byone TSX _ Transfer stack pointer to X 
; TXA Transfer X to accumulator 
JMP Jump to new location TXS Transfer X to stack voi 
pointer 
JSR Jump + save return address TYA Transfer Y to accumulator 
LDA Load accumulator 


*These instructions are not available on the 65@2. 
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65C@2 SYSTEM MEMORY 
INC DEC STZ 


ASL LSR- ROL ROR 


| CMP,ADC,SBC,TSB,TRB 
| AND,ORA,EOR,BIT 


LDA STA 


ACCUMULATOR 


ASL LSR ROL ROR 
LDA CMP ADC _ SBC 
AND ORA EOR_ BIT 
DEA INA 


X-REGISTER 


LDX 


INX DEX CPX ba—Tay 


PROGRAM 
COUNTER 


POINTER 
PHA PLA PHP PLP 
JSR RTS BRK ARTI 
PLX PHY 


65C@2 STACK 
($100 $1FF) 


STATUS 


CLC SEC CLD SED CLV 
CLI SEI 


NOTE: Solid arrows indicate a transfer of data. 
Dashed arrows indicate a transfer of information. 


Figure 2-1. Usage chart of 65C@2 instructions. 


execute another. In fact, the time it takes to execute one general type of 
instruction will even vary depending on how the instruction is told to access 
the data on which it is to operate (that is, its ““addressing mode’’). 


Table 2-2 sets out the times required to execute each instruction in units of 
65C@2 “machine cycles” for each valid addressing mode (addressing modes 
will be discussed in detail later in this chapter). The length of a 65C02 machine 
cycle is fixed by the frequency of the clock signal fed into the 65C@2 micro- 
processor. On the //c, this clock signal is 1.023 megahertz, which means that 
every machine cycle takes 0.9775 (1/1.023) microsecond to perform. 


It is often convenient to know exactly how long it will take to execute a 
particular instruction when precise timing loops must be generated in soft- 
ware. We will see an example of this in Chapter 9, where a program is 
presented that can generate musical notes of specific frequencies. 
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Table 2-2. 65C02 instruction set and cycle times. 


Instruction 
Mnemonic 


ADC 


AND 


ASL 


BCC 
BCS 
BEQ 
BIT 


BMI 
BNE 
BPL 

BRA 
BRK 
BVC 
BVS 


Assembler 
Operand Format 


#num 


zpage 
zpage,X 


“(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


#num 


zpage 
Zpage,X 


“(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


[accumulator] 


zpage 
Zpage,X 
abs 

abs ,X 


disp 
disp 
disp 


*#num 


Zpage 


“zpage,X 


abs 


*abs,X 


disp 
disp 
disp 


“disp 


[implied] 
disp 
disp 


Opcode Number 


Byte 


69 
65 
75 
72 
61 
71 
6D 
7D 
79 


29 
25 
35 
32 
21 
31 
2D 
3D 
39 


OA 
06 
16 
OF 
1E 


90 
BO 
FQ 


89 
24 
34 
2C 
3C 


30 
DO 
10 
80 
00 
50 
70 


of Bytes 


Nm NM B&B NY NH NY NH WWNNN KN NN N WWNNK WWWNHNNNNN WWWNNNN WN WN 


Number of 
Clock Cycles Notes 
2 
3 
4 
5 
6 
5 (1) 
4 
4 (1) 
4 (1) 
2 
3 
4 
5 
6 
5 (1) 
4 
4 (1) 
4 (1) 
2 
5 
6 
6 
6 (3) 
2 (2) 
2 (2) 
2 (2) 
2 
3 
4 
4 
4 
2 (2) 
2 (2) 
2 (2) 
2 (2) 
7 
2 (2) 
2 (2) 


(continued) 
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Table 2-2. 65C0@2 instruction set and cycle times (continued). 


Instruction Assembler Opcode Number Number of 
Mnemonic Operand Format Byte of Bytes Clock Cycles Notes 

CLC [implied] 18 1 2 
CLD [implied] D8 1 2 
CLI [implied] 58 1 2 
CLV [implied] B8 1 2 
CMP #num C9 2 2 
zpage C5 2 3 
zpage,X DS 2 4 
“(zpage) D2 2 5 
(zpage,X) Cl 2 6 

(zpage),Y Di 2 5 (1) 
abs CD 3 4 

abs X DD 3 4 (1) 

abs, Y D9 3 4 (1) 
CPX #num EO 2 2 
zpage E4 2 3 
abs EC 3 4 
CPY #num CO 2 2 
zpage C4 2 3 
abs CC 3 4 
DEA *[accumulator] 3A 1 2 
DEC zZpage C6 2 5 
zpage,X D6 2 6 
abs CE 3 6 

abs,X DE 3 6 (3) 
DEX limplied] CA 1 2 
DEY [implied] 88 1 2 
EOR #num 49 2 2 
Zpage 45 2 3 
zpage,X 55 2 4 
“(zpage) 52 2 5 
(zpage,X) 41 2 6 

(zpage), Y 51 2 5 (1) 
abs 4D 3 4 

abs,X 5D 3 4 (1) 

abs, Y 59 3 4 (1) 
INA *[accumulator] 1A 1 2 


(continued) 
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Table 2-2. 65C0@2 instruction set and cycle times (continued). 


Instruction 
Mnemonic 


INC 


INX 
INY 
JMP 


JSR 


LDA 


LDX 


LDY 


LSR 


NOP 
ORA 


Assembler 


Operand Format 


Limplied] 
limplied] 


abs 


(abs) 


*(abs,X) 


abs 


#num 


zpage 
Zpage,X 


*(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


#num 
zpage 
Zpage,Y 
abs 
abs, Y 


#num 
zpage 
Zpage,X 
abs 
abs,X 


[accumulator] 
Zpage 
zpage,X 

abs 

abs,X 


[implied] 


#num 


zpage 
Zpage,X 


“(zpage) 


Opcode Number 


Byte 


E6 
F6 
EE 
FE 


E8 
C8 


4C 
6C 
7C 


20 


A9 
AS 
B5 
B2 
Al 
Bl 
AD 
BD 
B9 


A2 
A6 
B6 
AE 
BE 


AO 
A4 
B4 
AC 
BC 


4A 
46 
56 
4E 
SE 


EA 


09 
05 
15 
12 


of Bytes 


NNNN RB WWNNKR WWNNN WWNNN WWWNONNNNN Ww WWW = = WwWwN Nd 


Number of 
Clock Cycles Notes 


MWMABWN NY DAADUN HHPAWN HPA WN HAHAAUWAAMNIHWN BD AAW NY YN AQAA UW 


(3) 


(4) 


(1) 


(1) 
(1) 


(1) 


(1) 


(3) 


(continued) 
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Table 2-2. 65C@2 instruction set and cycle times (continued). 


Instruction Assembler Opcode Number Number of 
Mnemonic Operand Format _ Byte of Bytes Clock Cycles _ Notes 

(zpage,X) 01 ? 6 

(zpage),Y 11 2 5 (1) 
abs 0D 3 4 

abs,X 1D 3 4 (1) 

abs,Y 19 3 4 (1) 
PHA [implied] 48 1 3 
PHP Limplied] 08 1 3 
PHX *[implied] DA 1 3 
PHY *[implied] 5A 1 3 
PLA [implied] 68 1 4 
PLP [implied] 28 1 4 
PLX *C{implied] FA 1 4 
PLY *[implied] 7A 1 4 
ROL [accumulator] 2A 1 2 
Zpage 26 2 5 
zpage,X 36 2 6 
abs 2E 3 6 

abs,X 3E 3 6 (3) 
ROR {accumulator] 6A 1 2 
Zpage 66 2 5 
Zpage,X 76 2 6 
abs 6E 3 6 

abs,X 7E 3 6 (3) 
RTI [implied] 40 1 6 
RTS limplied] 60 1 6 
SBC #num E9 2 2 
Zpage E5 2 3 
zpage,X FS 2 4 
“(zpage) F2 2 5 
(zpage,X) El 2 6 

(zpage),Y Fl 2 5 (1) 
abs ED 3 4 

abs ,X FD 3 4 (1) 

abs, Y F9 3 4 (1) 
SEC [implied] 38 1 2 
SED [implied] F8 1 2 


(continued) 
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Table 2-2. 65C02 instruction set and cycle times (continued). 


Instruction Assembler Opcode Number Number of 
Mnemonic Operand Format Byte of Bytes Clock Cycles Notes 

SEI limplied] 78 | 2 
STA zpage 85 2 3 
zpage,X 95 2 4 
*(zpage) 92 2 5 
(zpage,X) 81 2 6 

(zpage), Y 91 2 5 (1) 
abs 8D 3 4 

abs,X 9D 3 4 (1) 

abs, Y 99 3 4 (1) 
STX Zpage 86 2 3 
zpage,Y 96 2 4 
abs 8E 3 4 
STY Zpage 84 2 3 
zpage,X 94 2 4 
abs 8C 3 4 
STZ *zpage 64 2 3 
*zpage,X 74 2 4 
*abs 9C 3 4 
*abs,X 9E 3 5 
TAX [implied] AA 1 2 
TAY [implied] A8 1 2 
TRB *zpage 14 2 5 
*abs IC 3 6 
TSB *“zpage 04 2 5 
*abs OC 3 6 
TSX [implied] BA 1 2 
TXA [implied] 8A 1 2 
TXS [implied] 9A 1 2 
TYA limplied] 98 1 2 


Instructions marked with an asterisk are not available on the 6502. 
Notes: 


(1) Add one clock cycle if a page boundary is crossed. 

(2) Add one clock cycle if a branch occurs to a location in the same page; add two 
clock cycles if a branch occurs to a location in a different page. 

(3) Add one clock cycle if a page boundary is crossed; always 7 cycles on the 6502. 

(4) 5 cycles on the 6502. 


See Table 2-3 for a description of the assembler operand formats. 
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65C@2 Registers 


While the 65C@2 is executing a program, it makes use of the six internal 
registers that are shown in Figure 2-2. These registers are used to manipulate 
data in the manner dictated by the program that is executing and also to 
make the 65C@2 aware of various aspects of the status of the system: where 
the next instruction to be executed is located, where the next free space in 
the stack is located, and what the status of its seven internal flags is. A detailed 
understanding of these registers is important before a 65CQ@2 assembly-lan- 
guage program can be written. We will now take a closer look at each of the 
six registers. 


Ul Q 
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7 Yy 
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Figure 2-2. The 65C02 registers. 


The Accumulator—A 


The 65C@2 supports two simple arithmetic instructions: ADC (add with 
carry) and SBC (subtract with carry). Both of them require that the first of 
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the two operands in the addition or subtraction be contained in the accu- 
mulator register, A. After the arithmetic has been performed, the result is 
stored in A. This is how it gets its name—it “accumulates” the results of 
arithmetic operations that are performed. The accumulator is an 8-bit register 
and so can hold numbers from @ to 255 only. 


The accumulator is unique in that it is the only one of the 65C@2’s registers 
that can be used to perform the logical instructions, namely, EOR (logical 
“exclusive-or’’), ORA (logical ‘“‘or’’), and AND (logical ‘‘and”’), or any of the 
bit-shifting instructions, namely, ASL (arithmetic shift left), LSR (logical shift 
right), ROL (rotate left), and ROR (rotate right). (You should note, however, 
that the bit-shifting instructions can also operate directly on memory loca- 
tions.) 


Here are the 65C@2 instructions that directly use and affect the accumula- 
tor: 


Arithmetic : ADC, SBC 

Increment : INA (not on 65@2) 

Decrement : DEA (not on 65@2) 

Logical : AND, ORA, EOR, BIT, TRB (not on 6502), TSB (not on 6502) 
Bit-shifting : ASL, LSR, ROL, ROR 
Compare : CMP 

Store in memory : STA 

Load from memory or with data : LDA 

Store on stack : PHA 

Load from stack : PLA 

Inter-register transfer : TAX, TAY, TXA, TYA 


The Index Registers—X and Y 


Like the accumulator, the X and Y index registers are eight bits in size and 
can contain numbers from @ to 255. 


As their name suggests, the index registers are used primarily to locate 
elements contained in data structures in memory, such as a series of elements 
in a one-dimensional array. This is done by fixing the beginning address of 
the data structure and then simply adjusting the index register so that the 
sum of the beginning address and the index register is equal to the address 
of the element that is to be accessed. 


The 65C@2 supports several special instructions that directly use and affect 
the index registers: 


@® Increment : INX, INY 
@ Decrement : DEX, DEY 


2/The 65C02 Microprocessor [ _| 23 


® Inter-register transfer : TAX, TAY, TXA, TYA, TXS, TSX 
@ Store in memory : STX, STY 

@ Store on stack : PHX (not on 6502), PHY (not on 6502) 

@ Load from stack : PLX (not on 6502), PLY (not on 65@2) 
® Load from memory or with data : LDX, LDY 

@ Compare : CPX, CPY 


Note that the logical instructions and bit-shifting instructions that can be 
used with the accumulator cannot be used with the index registers. 


The Processor Status Register—P 


The 8-bit processor status register holds the states of seven one-bit flags or 
“status” bits that are referenced by the 65C@2 when it is executing many of 
its instructions. (One bit in the processor status register, bit 5, is not used by 
the 65C@2.) Each of these flags has a specific meaning and can markedly affect 
how instructions are executed. For example, the 65C@2 supports a series of 
“branch on condition” instructions (BCC, BCS, BPL, BMI, BEQ, BNE, BVC, 
BVS), each of which can be used to examine the status of a particular flag 
and to cause the program to ‘‘jump’”’ to a new location if the condition is met 
or to continue on with the next instruction in memory if it is not. (There is 
also a “branch always” instruction, BRA, that will cause an unconditional 
jump.) 

Although almost all instructions will cause flags in the processor status 
register to be adjusted after they have been executed, the following instruc- 
tions explicitly affect them: 


® Clear and set the carry flag : CLC, SEC 

® Clear and set the decimal flag : CLD, SED 
@ Clear and set the interrupt flag : CLI, SEI 
® Clear the overflow flag : CLV 


Let’s take a look at each of these seven flags right now. 


Carry Flag (C) 


The 65C@2 uses the carry flag in three quite different ways. 

First, the carry flag represents the “ninth” bit in any unsigned addition 
(ADC) or subtraction (SBC) operation that is performed. (“Unsigned’’ means 
that all eight bits of a byte are used to represent the magnitude of a number.) 
It can be examined after the addition or subtraction in order to determine 
whether the result is outside the range of numbers that can be stored in the 
8-bit accumulator. This allows for easy manipulation of numbers that use 
more than one byte. 
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The 65C@2 can perform arithmetic in one of two modes: binary and decimal. 
The mode used depends on the setting of the status register’s decimal mode 
flag (see below). 


In binary mode, each byte is considered to represent a simple unsigned 
binary number from @...255. When arithmetic operations are performed, 
the standard rules for adding or subtracting two binary numbers are followed. 


In decimal mode, however, each half of the byte is considered to represent 
a single decimal digit from @ to 9; this means that only those decimal numbers 
from 0@ . . .99 can be represented. When arithmetic operations are performed 
on such numbers, the result is always stored in the same decimal format. 


In either mode, before any arithmetic is performed, the carry flag must be 
cleared with a CLC instruction, in the case of addition, or set with a SEC 
instruction, in the case of subtraction. (If multibyte arithmetic is being per- 
formed, then the carry is adjusted only at the beginning of the sequence of 
additions or subtractions.) If the state of the carry flag changes after an 
addition operation, then the true answer is 256 (if in binary mode) or 100 (if 
in decimal mode) more than the number in the accumulator. If the carry flag 
changes after a subtraction, then the true answer is 256 (if in binary mode) 
or 100 (if in decimal mode) less than the number in the accumulator. 


The second use of the carry flag is as a ninth bit that participates whenever 
the ASL, LSR, ROL, and ROR bit-shifting instructions are executed. 


Third, the carry flag is used as a general-purpose flag that is acted on by 
the BCC (branch if C-flag is clear, or @) and BCS (branch if C-flag is set, or 1) 
instructions. As with all of the 65C02’s “branch on condition” instructions, 
BCC and BCS allow control of the program flow to be manipulated by the 
state of a flag in the processor status register (in this case, the carry flag). 


Zero Flag (Z) 


This flag is used to indicate whether the last data movement or arithmetic 
operation involved a zero result. If it did, then the Z-flag will be set (1); 
otherwise it will be cleared (@). 


There are two branch instructions that examine the status of the Z-flag to 
determine whether the branch should be performed: BEQ (branch if Z-flag is 
1, that is, result was equal to zero) and BNE (branch if Z-flag is 0, that is, 
result was not equal to zero). 


Interrupt Disable Flag (I) 


This flag is used to control how the 65C@2 will react when the electrical 
signal on its IRQ (interrupt request) pin is brought near @ volts. Such an 
interrupt can be generated by the Apple mouse or the //c’s two serial ports 
whenever they are ready to send information to, or receive information from, 
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the //c. If the I-flag is set using the SEI instruction, then all IRQ signals that 
may be generated will be ignored. If, however, the I-flag is cleared using the 
CLI instruction, then the 65C@2 will respond to IRQ signals when they occur 
by beginning a special interrupt sequence that is described in detail below in 
the section entitled ‘65CQ2 Interrupts.” 


Decimal Mode Flag (D) 


This flag is used to control how the 65C@2 is to perform addition and 
subtraction operations. If standard binary arithmetic is to be performed using 
the ADC and SBC instructions, then this flag must be cleared to 0 using the 
CLD instruction. As we saw when discussing the accumulator, in binary mode 
bytes are treated as unsigned binary numbers from @ to 255. 


If, however, the D-flag is set to 1 using the SED instruction, all arithmetic 
will be performed under the assumption that all numbers are stored in a 
special decimal format. In this format, one byte is used to store exactly two 
decimal digits from @ to 9. The first digit is stored in the high-order four bits 
and the other in the low-order four bits and the maximum number that can 
be stored is 99. When arithmetic operations are performed, the results will 
also be stored in this format. 


Break Flag (B) 


This flag is adjusted internally by the 65C@2 whenever an IRQ (interrupt 
request) interrupt is recognized by the 65CQ@2 or a BRK (break) instruction is 
executed. See the section below entitled “65CQ@2 Interrupts” for more infor- 
mation on these types of interrupts. When an IRQ interrupt is recognized, 
then the B-flag is cleared to 0; if a BRK instruction is executed, then it is set 
to l. 


Whenever an IRQ or a BRK interrupt is generated, the 65C02 begins to 
execute the same program (its address is held at locations $FFFE and $FFFF). 
It is often convenient, however, to determine what the source of the interrupt 
was so that a different action can be taken for each source. This is most easily 
done by having the interrupt-servicing program examine the state of the B- 
flag. 


Overflow Flag (V) 


The overflow flag is used primarily when performing arithmetic operations 
on signed numbers. Signed numbers are those that use bit 7 of a byte to hold 
the sign of the number (1 for negative, @ for positive). Bits @...6 are used to 
store the magnitude of the number in a special “two’s complement” format 
that will be described in Chapter 4. If the result of an addition or subtraction 
of two signed numbers is outside the range of numbers that can be stored in 
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this format (— 128... +127), then the V-flag will be set to 1; if the number is 
in range, however, the V-flag will be cleared to @. 


The V-flag can be explicitly cleared by using the CLV instruction. Surpris- 
ingly, there is no corresponding instruction to explicitly set the V-flag. 


The state of the V-flag can also be affected by using the BIT instruction. If 
you ‘‘BIT” any memory location, then a copy of bit 6 of the byte stored there 
will be placed in the V-flag. 


Two branch instructions make use of the V-flag: BVS (branch if V-flag is 1) 
and BVC (branch if V-flag is @). 


Negative Flag (N) 


The negative flag is used to indicate the sign of the last value that was 
directly transferred into the A, X, or Y register or that was put there by an 
instruction that performed an arithmetic operation (DEX, DEY, INX, INY, 
ADC; SBC, and so on). The 65C@2 considers any byte that contains a one in 
bit 7 to be negative. 


Two branch instructions make use of the N-flag: BPL (branch on plus, that 
is, N-flag is @) and BMI (branch on negative, that is, N-flag is 1). 


A BIT instruction can also be used to directly affect the state of the N-flag. 
When you ‘“‘BIT” any memory address, a copy of bit 7 of the byte stored there 
will be placed in the N-flag. If bit 7 is used to hold the status of some condition, 
then you can use BPL to branch if the status is off (@) or BMI to branch if it is 
on (1). We will see in later chapters that the //c uses bit 7 of several locations 
to represent the status of different hardware switches that can be controlled 
by software. 


The Stack Pointer—S 


As we saw earlier in this chapter, the 65C@2 uses the 256-byte area from 
$100 to $1FF as a hardware stack. This is a ‘‘last-in, first-out’ data area: the 
most recent information stored on the stack is always removed first. Infor- 
mation is usually placed on the stack by the “push” instructions, PHA, PHP, 
PHX, and PHY, and removed from the stack by the “pull” instructions, PLA, 
PLP, PLX, and PLY. (Information does not actually disappear after a pull, but 
it will be overwritten as soon as more information is pushed on to the stack.) 


The JSR (jump-to-subroutine) instruction also causes information to be 
placed on the stack. When the JSR instruction is executed, the address of the 
next instruction in memory after the JSR, minus one, is pushed on the stack 
(high-order byte first). When the corresponding RTS (return-from-subroutine) 
instruction is executed, this address is removed and the program resumes at 
that address (plus 1). 


2/ The 65C02 Microprocessor [___| 27 


The stack pointer register, S, is used to keep track of where in the 256-byte 
stack area the bytes are to be pushed to or pulled from; it always points to 
the next free space available in the stack area. When the system is first 
initialized, S is set equal to $FF. Then, whenever a byte is pushed on the stack, 
it is stored at location $100+S and then the stack pointer is decremented by 
one. Because S is decremented, the stack grows downward in memory. When 
bytes are pulled from the stack, they are taken from the top of the stack 
(location $100+S+ 1). The stack pointer is automatically incremented each 
time a byte is removed from the stack in this way. 


Interrupt conditions and interrupt-related instructions also affect the stack 
pointer (see the section below entitled ‘“65C@2 Interrupts” for a detailed 
discussion of interrupts). When an interrupt is recognized, a two-byte address 
and a copy of the processor status register is placed on the stack and the stack 
pointer is decremented by three. When the corresponding RTI (return-from- 
interrupt) instruction is executed, the three bytes on top of the stack will be 
placed in the status register and the program counter and the stack pointer 
will be incremented by three. 


Here are the 65C@2 instructions that directly affect the stack pointer reg- 
ister: 


® Inter-register transfer : TXS, TSX 
@ Push data on stack : JSR, PHA, PHP, PHX, PHY, BRK 
@® Pull data from stack : PLA, PLP, PLX, PLY, RTS, RTI 


The Program Counter—PC 


The program counter (sometimes called the instruction pointer) is the only 
16-bit register that the 65C@2 supports and is used to hold the address of the 
next instruction to be executed. This address will normally be that of the next 
instruction in the program, but not necessarily. There are several instructions 
that can be used to manipulate the flow of the program and to pass control 
to other parts of the program by adjusting the program counter accordingly. 
These are the JMP (jump) instruction, which acts like an Applesoft GOTO, the 
JSR (jump-to-subroutine) and RTS (return-from-subroutine) instructions, which 
act like an Applesoft GOSUB/RETURN combination, the branch-on-condition 
instructions (BCC, BCS, BEQ, BNE, BPL, BMI, BVC, BVS), and the branch 
always (BRA) instruction. The program counter is also affected by any hard- 
ware or software interrupt (BRK) and by the RTI (return-from-interrupt) 
instruction. 


65C@2 Addressing Modes 


A complete 65C@2 instruction is either one, two, or three bytes long. The 
first byte always represents the operation code (“‘opcode’’) for the instruction 
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itself and the remaining bytes (if any) represent the operand; if an operand is 
specified, it is either an address (one byte or two bytes) or immediate data 
(one byte). If the operand represents a two-byte address, then the first byte is 
always the lower two digits of the four-digit hexadecimal address (the allow- 
able addresses are in the range $0000 to $FFFF). 


An address that is specified after an opcode is not necessarily the address 
from which the instruction will read data or to which it will store data. In 
many instances, the 65C@2 uses this address to calculate another address 
(called the “effective address’) on which it does operate. Exactly how this 
calculation is to be performed depends on which of several “addressing modes” 
that can be used by that instruction has been selected. The 65C02 determines 
which addressing mode has been selected by examining the value of the 
opcode itself—each general type of instruction can have several opcode values 
associated with it, one for each valid addressing mode. The value of the opcode 
also dictates whether the operand is to be interpreted as immediate data 
instead of an address. 


We will now outline the various addressing modes that the 65C@2 supports. 
Before beginning, you should note that not all instructions are permitted to 
use each addressing mode. The ones that are supported by each instruction 
are indicated by entries in Table 2-2. The names of each of the addressing 
modes that the 65C@2 uses, and the operand formats used to represent these 
modes in an assembly-language program, are summarized in Table 2-3. Note 
that these operand formats are those used by the Merlin Pro assembler that 
was used to develop the examples presented in this book; other assemblers 
may require that slightly different formats be used. 


Immediate 


Immediate addressing is used whenever you want an instruction to act on 
a specific 8-bit number provided by the program rather than on a byte stored 
somewhere in memory. This 8-bit number is stored in the byte immediately 
following the opcode itself and forms the operand for the instruction. 


The immediate addressing mode is most useful for initializing a register to 
a constant value and for providing specific data on which an instruction is to 
operate. To select this addressing mode when using an assembler, the “#” 
symbol must be placed in front of the number in the instruction’s operand: 


LDA #49 load the accumulator with 49 (decimal) 
LDX #$43 load X with $43 (hexadecimal) 


It is often necessary to deal with the high-order or low-order byte of a two- 
byte address as an immediate quantity. To do this, you must use an assembler 
operand of the form ‘“#<ADDRESS'" (for the low-order byte) and 
‘“#>ADDRESS"” (for the high-order byte), where “ADDRESS” is the address 
being dealt with. Note, however, that the form of this type of operand applies 
to the Merlin Pro assembler only; most other assemblers require that a dif- 
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Table 2-3. 65C@2 addressing modes and assembler operand formats. 


Addressing Example of 
Mode Assembler Operand Format Instruction 
Immediate #num LDA #$45 
#<abs LDA #<$FDIB 
#>abs LDA #>$FD1B 
Absolute abs LDX $FE44 
zpage LDA $24 
Accumulator [Not applicable] ASL 
Implied [Not applicable] CLC 
Indexed indirect (zpage,X) LDA ($E0,X) 
(abs ,X) JMP ($2000,X) 
Indirect indexed (zpage),Y STA ($28),Y 
Absolute indexed abs,X LDA $2000,X 
abs, Y STA $0400,Y 
Zpage,X LDA $28,X 
Zpage,Y STX $22,Y 
Relative” disp BNE $BEAF 
Absolute Indirect (abs) JMP ($03EE) 
(zpage) STA ($E9O) 


Notes: “num 1-byte number 


abs = 2-byte address 
‘““<abs’ = low-order byte of a 2-byte address (or constant) 
‘“>abs” = high-order byte of a 2-byte address (or constant) 
“zpage’ = 1-byte zero page address 
“disp = 1-byte signed displacement 


*Relative addressing: An absolute address is usually specified in the operand in the 
program source code; the assembler converts the operand to a one-byte displace- 
ment to this address when the program is assembled. 


ferent method be used to specify which half of an address is to be dealt with. 
One assembler, the Apple 6502 Editor/Assembler, uses the same general method, 
but it reverses the meaning: ‘‘#>”’ is used to specify the low-order byte and 
“#<"’ is used to specify the high-order byte! 


Absolute 


The absolute addressing mode is used whenever the operand itself contains 
the address in memory on which the opcode is to operate. The two bytes 
required to store this address are stored low-byte first. 
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Here are some examples of how to use the absolute addressing mode: 


LDA $FE43 load the accumulator with the number stored at $FE43 
STY $1238 © store the Y register at location $1238 


Some instructions support an important variant of the absolute addressing 
mode, called zero page absolute, if the address specified is in the 65C@2 zero 
page (the first 256 bytes of memory). This mode is identified by a different 
opcode byte. In this mode, the opcode is followed by a one-byte address only 
because the high-order byte is implicitly zero. Most assemblers will recognize 
when a zero page location is being specified and will automatically select this 
addressing mode for you by changing the value of the opcode byte used by 
the instruction when the program is assembled. 


Accumulator 


Accumulator addressing is the mode used by all those opcodes that act on 
the accumulator alone and that require no address or immediate data on 
which to operate. These are the DEA and INA instructions and the bit-shifting 
instructions LSR, ASL, ROL, and ROR. There are no operand bytes for these 
instructions. Note, however, that some assemblers other than Merlin Pro 
(notably, the Apple 6502 Editor/Assembler) require that the letter ‘‘A’’ be 
entered in the operand field before the program source code can be properly 
assembled. 


Implied 


The 65C@2 supports many opcodes that do not act on immediate data or on 
memory locations, but rather on internal registers and status flags only. These 
opcodes require no operands because their actions are implicitly defined by 
the opcode itself and so the addressing mode used is called implied. 


Here are some examples of opcodes that use the implied addressing mode: 
PHA, PLA, PHP, PLP, CLD, CLI, BRK, DEX, INX, NOP, RTS, TAX. 


Zero-Page Indexed Indirect 


When the zero-page indexed indirect addressing mode is used, the operand 
is only one byte long and represents a location in zero page. The effective 
address on which the instruction acts is calculated by first adding the contents 
of the X register to the zero page location specified in the operand to obtain 
a resultant address. The effective address is represented by the two bytes that 
are stored at the resultant zero-page address and the very next address (low- 
order byte first). 
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For example, if X is 3 and the zero-page address is $EQ, then the effective 
address is stored at $E@+ 3 (low-order part) and $E@+4 (high-order part). 


You can select this addressing mode when using an assembler by using an 
instruction of the form 


STA ($E@,X) 


where the parentheses indicate that the effective address is not $E0+ X but 
rather the address stored at that location. 


Zero-Page Indirect 


The zero-page indirect addressing mode is unique to the 65C@2 and is not 
available on the 6502. The operand is one byte long and represents a location 
in zero page. The effective address is simply the address that is stored at this 
location and the very next one. Thus the zero-page indirect mode is the same 
as the zero-page indexed indirect mode, but without the X indexing. 


An assembler uses an instruction of the form 
STA C$E9@) 


to indicate that the zero-page indirect mode is to be used. 


Indirect Indexed 


Indirect indexed is a powerful addressing mode that is often used to access 
a block of memory that may not always begin at the same location in memory 
or that is longer than 256 bytes in length. The operand is one byte long and 
represents a zero page location; this zero page location, and the one imme- 
diately following it, contain the address (low-byte first) of the beginning of a 
data block in memory. These locations are said to “point to” this data block. 


When this addressing mode is used, the effective address on which the 
instruction is to operate is calculated by first taking the address of this data 
block from the zero page locations and then adding to it the contents of the 
Y register. 


Here is an example of how you would select the indirect indexed addressing 
mode when using an assembler: 


LDA (€$26),Y 


The parentheses around $26 mean “contents of’; it is the address stored at 
$26 (and $27) that will be used to calculate the effective address, and not $26 
itself. If the Y-register contains $FE and the address $400 is stored at $26/$27 
($00 in location $26 and $04 in location $27), then the accumulator will be 
loaded with the contents of memory location $4FE ($4FE = $400 + $FE). 
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Absolute Indexed 


The operand for the absolute indexed addressing mode is two bytes long 
and contains the absolute address of a memory location called a ““base address.” 
The effective address on which the instruction is to operate is calculated by 
taking this base address and adding to it the contents of the X register (if X 
indexing is selected) or of the Y register (if Y indexing is selected). 


Here are some examples of the use of this addressing mode: 


LDA $4660,xX load the accumulator with the contents of the location 
specified by $400+ X. 


STA $A®32,Y store the accumulator at the location specified by 
$A032+ Y 


There is a special version of this addressing mode, called zero page abso- 
lute indexed, that can be used by some instructions when the base address 
is in page zero. In this case, the operand is only one byte long and represents 
this zero page address. Most assemblers will automatically select this 
addressing mode for you if the operand is, indeed, in page zero. 


Relative 


The 65C02 supports a series of two-byte branch instructions that examine 
the 65C@2 status register to determine whether a change in the flow of the 
program should be made or not: BEQ, BNE, BPL, BMI, BCC, BCS, BVC, and 
BVS. Another instruction, not available on the 6502, BRA, can be used to 
unconditionally change the flow of the program. 


The first byte represents, as usual, the opcode for the instruction. The second 
byte represents the number that must be added to the address of the next 
instruction in memory in order to calculate the destination address of the 
branch. Because this byte represents a displacement from an instruction’s 
location rather than an absolute location, this addressing mode is called 
“relative.” 


There are restrictions on how far you can branch using relative addressing. 
In particular, you can only specify a relative address that is at most 127 bytes 
higher in memory or 128 bytes lower in memory (as measured from the 
address of the next higher instruction). Values from $00 . . . $7F represent the 
positive branches (@ .. . 127), and values from $80... $FF represent the neg- 
ative branches (— 128, — 127, ...,—1). Note that the values for negative branches 
are stored in a special “two's complement’ format; see Chapter 4 for a detailed 
description of this format. 


If you must transfer control to a destination location that is outside this 
range, you will have to use a JMP instruction instead. 
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Absolute Indirect 


This addressing mode is used by only one instruction, JMP. A two-byte 
operand is used and these two bytes define a location in memory that contains 
the low half of the address that is to be jumped to; the high half is stored in 
the next memory location. 


If you are using an assembler, then you would select this addressing mode 
by entering an instruction that looks like this: 


JMP €$1234) 


The parentheses around the operand indicate that it is not $1234 that is 
being jumped to but rather the address stored at $1234 (and $1235). 


The absolute indirect addressing mode is useful in situations where the 
ultimate destination of the jump instruction may be changed, perhaps by 
another program. Even if this other program places a new address at the 
operand address, the main program itself need not be changed. On the other 
hand, if the absolute addressing mode were used instead, then it would be 
necessary to modify the program and this may be difficult to do. The //c uses 
the indirect addressing mode whenever it has to jump to its character input 
or output subroutines. Whenever new input or output devices are activated, 
all that need be done is to change the address stored at the address specified 
in the operand—the main program will remain the same (see the discussion 
of the //c’s input and output links in Chapters 6 and 7). 


Absolute Indexed Indirect 


The absolute indexed indirect addressing mode is the other mode that is not 
available on the 6502. It works with the JMP instruction only and is of the 
form: 


JMP €$1234,X) 


The effective address that is jumped to is the one stored beginning at an 
address that is equal to the address specified in the operand plus the contents 
of the X-register. 


65C@2 Input/Output Handling 


Unlike the instruction sets of some microprocessors, the 65C@2 instruction 
set does not include any instructions that are specifically designed to perform 
input/output (I/O) operations like reading from the keyboard or writing to the 
video screen. Instead, all I/O operations are performed by using standard 
instructions to read data from or write data to addresses within the 65C@2’s 
standard 64K address space to which I/O devices are “‘connected.”’ These 
addresses do not usually represent real RAM or ROM memory locations 
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(memory that holds video display information iis one exception) but, never- 
theless, are accessed in exactly the same way as if they did. 


This method of handling I/O is called ‘“‘“memory-mapped I/O” because the 
I/O devices form a logical part of the 65C@2’s 64K memory space itself and so 
no special instructions are required to make use of them. The //c contains 
several addresses that are used to control various aspects of its hardware 
environment. As we will see at the end of this chapter, except for those 
addresses that relate to the video display, these addresses are all mapped to 
locations from $C000 .. . $COFF. Note that some of these I/O locations can be 
accessed in order to switch between one of two hardware states, for example, 
text or graphics display, primary or alternative character set, and 40-column 
or 80-column display. Thus, they are called ‘‘soft switch’ /O memory loca- 
tions. 


65C@2 Interrupts 


There are three input pins on the 65C0@2 integrated circuit that are called 
RESET, IRQ (interrupt request), and NMI (non-maskable interrupt): When 
the electrical signals at each of these three pins is high (near +5 volts) the 
65C@2 goes about performing its normal functions. If, however, one of these 
pins is suddenly brought low (near @ volts), one of three special “‘interrupt’’ 
sequences may begin, depending on which pin has been affected. An interrupt 
sequence can also be generated in software by using the 65C02 BRK (break) 
instruction. 


We won't concern ourselves with NMI interrupts because they are not used 
on the //c. 


RESET interrupts can be generated in three different ways on the //c: when 
the power is turned on, when [control-RESET] is pressed, and when [control- 
OPEN-APPLE-RESET] is pressed. (See Chapter 6.) RESET signals are usually 
used to initialize the system to its power-on state or to break out of a running 
program. 


IRQ interrupts are usually generated by I/O devices whenever they have 
information available to be read (input devices) or whenever they are ready 
to receive information (output devices). Generally speaking, when the 65C0@2 
detects an IRQ signal, it stops executing the main program and starts exe- 
cuting a special interrupt-handling subroutine that has been installed. When 
this subroutine finishes, control returns to the main program at the point 
where it was interrupted and execution of that program continues. 


Since the 65C@2 can be interrupted like this, it is not necessary for the main 
program to continuously monitor (or “poll’’) the I/O devices to determine 
when one is ready to be dealt with. This means that the program can execute 
much more quickly and efficiently. 
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IRQ interrupts may be generated on the //c in any of the following circum- 
stances: 


@ When the mouse is moved. (See Chapter 10.) 


@® When a video vertical blanking signal occurs. (This occurs every 1/60th 
of a second; see Chapter 10.) 


@ When a serial port is ready to send or receive data. (See Chapter 11.) 


@ When the state of the signal on pin 5 of either of the two serial ports 
changes. (This is the serial device’s ‘‘data carrier detect’ (DCD) line; see 
Chapter 11.) 


@® When a key is pressed or released. (See Chapter 11.) 


@ When the state of the signal on pin 9 of the external disk drive connector 
changes. (This is called the “external interrupt’ line; see Chapter 11.) 


Each type of 65C@2 interrupt is associated with a two-byte vector that holds 
the address of the interrupt-handling subroutine that will be called when the 
interrupt occurs. These vectors are all stored in the high end of of the 65C@2 
memory space from $FFFA to $FFFF. The specific vector locations for each 
type of interrupt and the addresses of the interrupt-handling routines to which 
they point are shown in Table 2-4. Note that all of the vector addresses change 
when ProDOS is being used. Most of ProDOS resides in a special “bank- 
switched RAM” area from $D000...$FFFF that is normally occupied by 
Applesoft and the system monitor ROMs (see Chapter 8). Thus, the interrupt 
vectors within this RAM area (from $FFFA to $FFFF) can be changed as desired 
and they will take effect whenever bank-switched RAM is active. 


The interrupt-handling routines on the //c ultimately pass control to other 
addresses that are specified in user-definable vector locations. These user 
vector locations are also shown in Table 2-4. Note that a user-defined interrupt 


Table 2-4. 65C@2-Apple //c interrupt locations. 


Interrupt Address of Location of 
Interrupt Type Vector Location Interrupt Handler User Vector 
RESET $FFFC/$FFFD $FA62 or $FFCB $03F2* 
IRQ $FFFE/$FFFF $C803 or $FF9B $03FE 
BRK $FFFE/$FFFF $C803 or $FFIB $03FO 
we so” 
when the ProDOS 


bank-switched 
RAM area is active 
only 


*Control is passed to the Reset user vector only if the number stored at $3F4 (the 
powered-up byte) is equal to the logical exclusive-OR of the number stored at $3F3 
and the constant $A5. 
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subroutine that is used to handle interrupts generated by an IRQ signal, or a 
BRK command, must end by executing an RTI (return-from-interrupt). Fail- 
ure to do this will cause the system to crash in an unpredictable way. 


The three basic types of interrupts supported by the 65C@2 on the Apple //c 
will now be discussed in detail. 


Reset Interrupt 


The reset interrupt is used to cause the system to stop executing the current 
program and to begin a sequence of instructions that start at the address 
stored in the reset vector at $FFFC/$FFFD (low-order byte first). On the //c, 
the reset vector points to a subroutine beginning at $FA62 (the ProDOS reset 
vector actually points to another subroutine that ultimately calls $FA62). This 
subroutine takes care of initializing the //c to a known state and will pass 
control to a user-definable subroutine whose address is stored at $3F2 and 
$3F3 (low-order byte first) if the logical exclusive-OR of the value stored at 
$3F3 and the constant $A5 is the same as the value stored at $3F4 (which is 
called the powered-up byte). If it isn’t, then the disk drive will start up just 
as it does when the //c is first turned on. 


The reset interrupt is automatically generated whenever the power to the 
65C@2 is first turned on. As we will see in Chapter 6, it can also be generated 
by pressing the CONTROL and RESET keys on the //c’s keyboard at the same 
time. Specific examples of “trapping” the reset interrupt by adjusting the 
user vector at $3F2/$3F3 and the powered-up byte at $3F4 will also be given 
in Chapter 6. 


A reset interrupt is normally used only in panic situations where the pro- 
gram that is running must be stopped immediately or when you are running 
programs that do not have an exit command. 


Interrupt Request (IRQ) 


The 65C@2 will only respond to an active IRQ interrupt signal if the I-flag 
in the processor status register is @ (this flag is cleared using the CLI instruc- 
tion). If the I-flag is set to 1 (using the SEI instruction), then the IRQ signal 
will be ignored and no further IRQ interrupts will be dealt with until after 
the I-flag is cleared. 


If the I-flag is @ and an active IRQ signal is generated, then the 65C0@2 
responds by first completing the current instruction being executed. The 
following sequence of events then takes place: 


@ The current program counter is stored on the stack. (This will be the 
address, less 1, of the next instruction in the program to be executed after 
the interrupt has been dealt with.) 
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® The B-flag in the processor status register is cleared to 0 and then the 
register is stored on the stack. 


@ The I-flag in the processor status register is set to 1. (This disables sub- 


sequent IRQ operations until the current interrupt is dealt with; see 
below.) 


After these operations have been performed, the program counter is loaded 
with the address that is stored in the IRQ vector at $FFFE/$FFFF (low-order 
byte first), and then the interrupt-handling program that begins at that address 
is executed. The address stored in the IRQ vector on the //c is usually $C803, 
or if ProDOS is processing data when the interrupt occurs, at $FF9B; the 
ProDOS subroutine simply does a bit of housecleaning before calling $C803 
itself. 


The subroutine beginning at $C8@3 first determines whether the source of 
the interrupt was an IRQ signal or a BRK instruction (BRK is discussed in 
the next section). If the source was an IRQ signal, the subroutine calls two 
ROM subroutines that are used to handle mouse port and serial port inter- 
rupts. These subroutines will either handle the interrupt internally or pass 
control through to your own interrupt-handling subroutine, depending on the 
values stored in certain memory locations. We will see how to manipulate 
mouse port and serial port interrupts in Chapters 10 and 11. 


If the interrupt is not handled internally by the //c, then control will pass 
to the address stored at user vector locations $3FE and $3FF. Thus, to properly 
handle an IRQ interrupt, an interrupt-handling subroutine must be placed in 
memory and its starting address must be stored at $3FE/$3FF. This subroutine 
must pass control back to the main program by ending with an RTI (return 
from interrupt) instruction. (Alternatively, if ProDOS is being used, you can 
install your interrupt-handling routine by using a special ProDOS interrupt 
command. See Apple’s ProDOS Technical Reference Manual for more infor- 
mation on this feature of ProDOS.) 


The BRK Instruction 


One of the 65C@2’s instructions allows you to simulate the effect of an IRQ 
signal in software. This is the one-byte BRK (break) instruction represented 
by a “00” byte. BRK is primarily used when debugging a program because 
when a program encounters it, control is directed to a user-definable subrou- 
tine that can display information relating to the state of the program at that 
particular point. For example, the contents of important memory locations 
and of the 65C@2 registers can be displayed. If the state is not as expected, 
then you can start bug-hunting. 


Whenever the 65C@2 encounters a BRK instruction, the B-flag in the pro- 
cessor status register is set to 1 and then an interrupt sequence much like the 
one generated by an IRQ signal is started (the main difference is that the 
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address stored on the stack is the address of the BRK instruction plus two). 
Since the address of the interrupt-handling routine used is the same one used 
for IRQ interrupts, that routine should properly check the status of the B-flag 
to determine what caused the interrupt. In fact, this is what is done on the //c. 
Once the //c determines that the interrupt was caused by a BRK instruction, 
control is passed to the address stored at the user vector locations $3F0 and 
$3F1 (low-order byte first). This vector usually contains $FA59, the address 
of the subroutine that displays the current contents of all the registers, but 
can be changed to point to any other interrupt-handling routine that you care 
to use. 


The 65C@2 Memory Space on the //c 


In this section, we are going to take a look at the layout of the memory 
space that is available to the 65C02 as implemented on the //c. This memory 
space can be thought of as being composed of three general parts: RAM, ROM, 
and input/output (I/O) memory addresses. The //c’s main RAM memory map 
is shown in Figure 2-3. Its ROM and I/O memory map is shown in Figure 2-4. 


In the following sections, we will encounter several situations where the 
same logical memory address is used by more than one actual physical mem- 
ory location. The //c uses a set of special “soft switches’ to select which of 
these locations is to be active at any given time. (A ‘‘soft switch” is a memory 
location that, when accessed from a software program, causes a change in the 
/ic’s hardware environment.) This is necessary because the 65C02 would become 
hopelessly confused if several locations sharing the same address were active 
at the same time. We will be looking at the soft switches that the //c uses to 
manage its memory space in Chapter 8. 


RAM Memory 


The area of RAM memory that is most often used on the //c is that part of 
‘main’ (as opposed to “auxiliary’’) memory that extends from locations $0000 
to $BFFF. As indicated in Figure 2-3, some regions within this range are 
dedicated for special uses. Here is a summary of the usage of the main RAM 
memory locations: 


© $0000-$@0FF. This is the 65CQ@2 zero page and it is used extensively by 
all parts of the //c’s operating system, including the system monitor (see 
Chapter 3), the Applesoft interpreter (see Chapter 4), and the disk oper- 
ating system (see Chapter 5). Those locations available for use by your 
own programs are shown in Table 2-5. 


® $0100-$01FF. This is the 65C@2 stack area and is also used for temporary 
data storage by the Applesoft interpreter. (See Chapter 4.) 
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$Dx BANK2 


$6200 


HIGH-RES 
PAGE2 
HIGH-RES 
PAGE1 


$4000 


$2000 
$ocoa 

$0800~a,___ | «—TEXT/LOW-RES PAGE2 
$9400-»,——_________| «— TEXT/LOW-RES PAGE1 
$0200 ~— ZERO PAGE and STACK 


Figure 2-3. Memory map of main RAM. 


® $0200-$02FF. This area of memory is normally used as an input buffer 
whenever character information is entered from the keyboard or from 
diskette. (See Chapter 6.) 


® $0300-$03CF. This area of memory is not used by any of the built-in 
programs in the //c and so is available for use by your own programs. It 
is an ideal location for storing small assembly-language programs that 
are called from Applesoft and most of the examples presented in this 
book are to be loaded here. 


@ $03D0-$03FF. Portions of this area of memory are used by the disk 
operating system, Applesoft, and the system monitor for the purpose of 
storing position-independent vectors to important subroutines that can 
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$FFFF 
STANDARD 
SYSTEM MONITOR 
$F800 
$FOOO 
APPLESOFT 
INTERPRETER 
$EO00 
$D000 
EXTENSIONS TO SYSTEM 
MONITOR AND SUPPORT 
SUBROUTINES FOR THE 
BUILT-IN 1/0 DEVICES 
$C100 
1/0 MEMORY 
$COO0 


Figure 2-4. Memory map of ROM and I/O memory. 


be located anywhere in memory (such as interrupt-handling subrou- 
tines). See Appendix IV for a complete description of how this area is 
used. 


$6400-$07FF. This is pagel of video memory that is used for displaying 
both the primary text screen and the primary low-resolution graphics 
screen. (See Chapter 7.) It is also used for displaying one-half of the text 
screen when in 80-column mode. Note that there are 64 bytes in this area 
that are not actually used for the video display; they are called ‘‘screen 
holes” and are used for data storage by the //c’s built-in I/O devices. 


$0800-$@BFF. This is page2 of video memory that is used for displaying 
both the secondary text screen and the secondary low-resolution graphics 
screen. (See Chapter 7.) Since page2 is rarely used, this area of memory 
is normally used for program storage; in fact, the default starting position 
for an Applesoft program is $801. 


® $0C00-$1FFF. This area of memory is free for use. 


®@ $2000-$3FFF. This is pagel of video memory that is used for displaying 
the primary high-resolution graphics screen. (See Chapter 7.) 
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© $4000-$5FFF. This is page2 of video memory that is used for displaying 
the secondary high-resolution graphics screen. (See Chapter 7.) 


@ $6000-$BFFF. This area of memory is normally free for use. However, 
the upper part of it (above $9600) will be used if a disk operating system 
is installed. (See Chapter 5.) 


Main memory also contains an additional 16K of RAM memory that is 
located from $D000 to $FFFF (the 4K block from $D000 to $DFFF is dupli- 
cated). The ProDOS disk operating system occupies most of this area and so 
it cannot be safely used by other programs. This 16K area is called bank- 
switched RAM and will be discussed in detail in Chapter 8. 


The //c also comes with 64K of ‘‘auxiliary’””» RAM memory that can be used 
for program and data storage. This memory occupies the same address spaces 
as the 64K of main RAM memory and so can be thought of as a ‘‘twin’’ memory 
space. There are slight differences, however, in how some of the areas within 
this memory are interpreted. For example, the two memory areas correspond- 
ing to the page2 video areas in main memory are not reserved for those 
purposes in auxiliary memory. Furthermore, the two areas corresponding to 
pagel video areas are not used for video display purposes unless 80-column 
text mode is active or unless a double-width graphics mode is active. These 
differences will be discussed in greater detail in Chapter 7. 


Input/Output (I/O) Memory 


The //c’s /O memory space corresponds to those addresses from $C0QO to 
$COFF. Although these addresses may be read from or written to in exactly 
the same way as normal RAM or ROM memory locations, there is no memory 
stored at these locations. Instead, whenever these locations are accessed, a 
physical change in the system can be effected (for example, the graphics 
display can be turned on, the character set can be changed, or the disk drive 
motor can be turned on), the status of an I/O device can be read, or data can 
be transferred to or from the I/O device. This method of handling I/O oper- 
ations is called memory-mapped I/O. 


For example, consider the //c’s keyboard. The keyboard has been wired into 
the system in such a way that it can be be controlled by using the locations 
$C000 and $C@1@. (See Chapter 6.) To determine whether a key has been 
pressed, address $C000 is examined; if bit 7 at this “location” (the keyboard 
strobe bit) is 1, then a key has indeed been pressed. Address $CQ10 is accessed 
to clear the keyboard strobe bit. Even though an address is accessed in order 
to read and clear the keyboard, there is no memory chip on the //c that 
corresponds to this address. 


All of the //c’s I/O memory locations will be discussed in later chapters. A 


summary of the meaning of each of these locations is contained in Appendix 
II. 
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Table 2-5. 65C@2 zero page locations not used by the system monitor, 
Applesoft, or ProDOS. 


Available Locations: 


$96 $087 $808 $89 

$19 $1A $1B $1C $1D $1E 
$CE $CF 

$D7 

$E3 

$EB $EC $ED $EE $EF 
$FA $FB $FC $FD $FE $FF 


ROM Memory 


As you can see from Figure 2-4, ROM memory on the //c extends from 
locations $C100 to $FFFF. Here is a summary of ROM memory usage: 


® $C100-$CFFF. This ROM area contains extensions to the system monitor 
and subroutines to support the 80-column text display, the printer port, 
the modem port, the mouse, and the disk drive. 

® $D000-$F7FF. This is the Applesoft ROM space. (See Chapter 4.) 


® $F800-$FFFF. This is the standard system monitor ROM space. (See 
Chapter 3.) 


The permanent programs contained within these ROM areas are often 
called “firmware” to distinguish them from ‘‘software’’ that is loaded into 
RAM memory from a diskette. 


Note that the addresses used by the Applesoft and system monitor ROMs 
($D000 ...$FFFF) are the same as the ones used by the //c’s bank-switched 
RAM space. 


Further Reading for Chapter 2 


On 6502 assembly-language programming ... 


MCS6500 Microcomputer Family Programming Manual, MOS Technology, 
Inc., 1976. This book comes straight from the manufacturer of the original 
6502 microprocessor. 


R. Zaks, Programming the 6502, Sybex, 1978. 


L.A. Leventhal, 6502 Assembly Language Programming, Osborne/McGraw 
Hill, 1979. 
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M.L. deJong, Programming & Interfacing the 6502, With Experiments, 
Howard W. Sams & Co., Inc., 1980. 


D. Inman and K. Inman, Apple Machine Language, Reston Publishing Com- 
pany, Inc., 1981. 


R. Wagner, Assembly Lines: The Book, Softalk Books, 1982. 


R.C. Haskell, Apple II 6502 Assembly Language Tutor, Prentice-Hall Inc., 
1983. 


On the 65C6@2 microprocessor .. . 


S. Hendrix, ‘‘The CMOS 65C0@2”, Byte, December 1983, pp. 443-452. This 
article reviews some of the limitations of the 6502 and introduces the 
new 65C@2 microprocessor. 


On machine cycle time... 


S. Wozniak, “Impossible Dream: Computing e to 116,000 Places With a 
Personal Computer’, Byte, June 1981, pp. 392—407. This article has inter- 
esting comments on the 6502’s effective machine cycle time on the Apple 
II (it’s the same on the //c). 


On memory usage by the 6502/Apple II... 


W.F. Luebbert, What’s Where in the Apple, Micro Ink, Inc., 1982. This book 
contains a comprehensive memory map for the Apple II. 


Assemblers (software) .. . 
The following assemblers operate in ProDOS: 


G. Bredon, Merlin Pro, Roger Wagner Publishing, Inc., 1984. 


G. Bredon, BIG MAC.C, A.P.P.L.E., 1984. This assembler is identical to 
Merlin Pro but is available to members of A.P.P.L.E. (Apple Pugetsound 
Program Library Exchange) only. 


ProDOS Assembler Tools, Apple Computer, Inc., 1983. 
The following assemblers operate in DOS 3.3: 


B. Sander-Cederlof, S-C Macro Assembler, S-C Software Corporation, 1983. 
R. Hyde, LISA, Lazerware, 1981. 
G. Bredon, Merlin Pro, Roger Wagner Publishing, Inc., 1984. 


The System Monitor 


The system monitor is a machine-language program that resides in the 
/ic’s ROM area and whose “cold-start’’ entry point to a special command 
interpreter is located at $FF59. It is called a “monitor” because it supports 
several commands that allow you to quickly and easily view and modify the 
contents of memory locations, programs loaded into memory, or 65CQ2 reg- 
isters. In addition, commands are available that can be used to run programs, 
to assist in the debugging of programs, and to perform general housekeeping 
functions (such as data movement or data comparison). 


The subroutines that make up the system monitor take up two large parts 
of the //c’s ROM area. The first part resides from $F800 to $FFFF and the 
second part from $C100 to $CFFF. Generally speaking, the first part is com- 
parable to the standard system monitor ROM that resided at the same loca- 
tions in the earlier Apple //e, Apple II Plus, and Apple II computers; the code 
is not identical, but virtually all of the starting addresses for its commonly 
used subroutines are the same as on older models. The internal ROM area 
from $C100 to $CFFF provides the additional space needed for the longer 
subroutines required to support the //c’s 80-column video display. It also 
holds the support subroutines for the built-in printer, modem, mouse, and 
disk drive interfaces. 


The subroutines contained within the system monitor perform most of the 
fundamental input/output (I/O) tasks needed to support programs running on 
the //c. Such tasks include reading a character from the keyboard, displaying 
a character on the video screen, displaying graphics on the video screen, and 
reading game controller input. Other subroutines required to support the 
monitor commands themselves are also found here, of course. In addition, 
there are numerous utility subroutines used by the code performing these 
tasks and commands. In the last section of this chapter, we will identify some 
of the more useful subroutines that can be accessed from Applesoft by using 
the CALL command or from assembly language by using the JSR (jump-to- 
subroutine) or JMP (jump) instructions. 


The usefulness of the system monitor is greatly enhanced by the fact that, 
being in ROM, its subroutines and command interpreter are always easily 
accessible. There are three main entry points to the system monitor command 
interpreter—OLDRST ($FF59), MON ($FF65), and MONZ ($FF69)—and con- 
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trol can be passed to them from Applesoft direct mode by entering the com- 
mands “CALL —167,” “CALL —155,” and “CALL —151,” respectively. (Note 
that Applesoft considers a ‘‘negative’’ decimal address to be equivalent to the 
standard positive address minus 65536; for example, $FF69 can be repre- 
sented as 65385 or 65385-65536 = —151.) After this has been done, the system 
monitor prompt symbol (the asterisk—‘*”’) will appear and you can begin to 
enter any of the commands that the system monitor supports (or, if ProDOS 
is active, any valid ProDOS commands). 


The //c reacts slightly differently to each of the above three CALLs to its 
standard entry points. The cold-start entry point, OLDRST (—167), will ini- 
tialize “normal” video mode (white characters on a black background), select 
the full-screen text video mode, and then enable the standard keyboard input 
and video screen output subroutines. It also deactivates the //c’s disk operating 
system (ProDOS) so that it must be reactivated before returning to Applesoft 
(see the discussion below of the BASIC and CONTINUE BASIC commands). 
After this has been done, control passes to the primary warm-start entry 
point, MON (—155), where the 65C@2’s decimal mode flag is cleared (to force 
binary arithmetic) and the speaker is beeped. Control then passes to the 
secondary warm-start entry point, MONZ (—151), which takes care of setting 
up the “"*”’ prompt symbol and interpreting commands that are entered from 
the keyboard. MONZ (—151) is the entry point that is most commonly used to 
enter the system monitor command interpreter. 


The System Monitor Commands 


The commands that the system monitor supports are summarized in Table 
3-1. Before we take a detailed look at these commands, let’s review the general 
command entry rules that must be followed. 


First of all, the system monitor “thinks” in hexadecimal. This means that 
it displays all addresses or data in a standard hexadecimal format and that 
all information must be provided to it in this format as well. Decimal numbers 
cannot be used. 


Addresses (from $0000 ... $FFFF) must normally be specified as four hex- 
adecimal digits but leading zeros may be omitted if you wish. If an address 
is entered that is longer than four digits, only the last four digits specified are 
used. Similarly, byte values (from $00... $FF) must normally be specified as 
two hexadecimal digits but, again, a leading zero may be omitted. If more 
than two digits are specified for a byte value, only the last two are used. 


The DISPLAY Command : Displaying the Contents of 
Memory 


After you have entered the system monitor, you can quickly read and display 
what is stored in any particular memory location by simply entering the 
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Table 3-1. Summary of System Monitor Commands. 


Command Name 


DISPLAY 


STORE 


MOVE 


VERIFY 


EXAMINE 


GO 


LIST 


NORMAL 
INVERSE 
ADD 


SUBTRACT 


BASIC 


Syntax 
addri.addre 


addri:bi be 


addr3<addri1i.addreMm 


addr3<addri1.addrevVv 


Ccontrol-E] 


addr1G 


addri1L 


N 
I 
b1+b2 


bi-b2 


Ccontrol-B] 


Description 


Displays the contents of 
memory from ‘“‘addr1”’ to 
“addr2”. 


Stores the values of bytes 
“b1’’, ‘‘b2”, ... into 
memory locations begin- 
ning at ‘‘addr1”’. 


Moves the block of mem- 
ory from ‘‘addrl’’ to 
“‘addr2’’ to the block 
beginning at ‘‘addr3”. 


Compares the block of 
memory from “addr1”’ to 
“‘addr2”’ to the block 
beginning at “addr3” and 
displays any differences. 


Displays the values to be 
stored in the 65C@2 reg- 
isters when “G” is used. 
Follow EXAMINE with 
STORE to set these val- 
ues. 


Runs the program begin- 
ning at “addrl”. 


Disassembles 20 lines of 
a machine language pro- 
gram beginning at 
“addr1”’. 

Set normal video. 

Set inverse video. 


Adds the bytes ‘“‘b1”’ and 
‘“b2”” and displays the 
result. 

Subtracts byte “b2” from 
byte “bl” and displays 
the result. 


Causes the system to 
enter Applesoft (cold). 


(continued) 
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Table 3-1. Summary of System Monitor Commands (continued). 


Command Name Syntax Description 
CONTINUE BASIC [control-C] Causes the system to 
enter Applesoft (warm). 
USER Ccontrol-Y] Causes the system to 
jump to location $3F8. 
KEYBOARD portfCcontrol-K] Causes the device in 


“port” to become the 
source of input. 


PRINTER portt€control-P] Causes the device in 
“port”? to become the 
current output device. 


b1,b2 represent byte values (in hexadecimal) 
addr1,addr2, addr 3 represent addresses of memory locations (in hexadecimal) 
port represents a valid port number (1, 2, 3, 4, 6, 7) 


hexadecimal address of the location and pressing [return]. For example, to 
display the number that has been stored at $FDOC, you would enter 


FD@C Creturn] 
and the system monitor will respond with 
FD@C- A4 


where A4 is the hexadecimal value of the byte stored at $FDOC. You can also 
just press [return] by itself to display the contents of the locations immedi- 
ately after the last one acted on, up to the edge of the next 8-byte boundary 
(i.e., locations ending in “7” or ‘“‘F’’). 

The contents of an entire range of memory can be displayed at once by 
typing in the first address, a period (‘‘.”), and then the last address. For 
example, to examine the 17 bytes of the system monitor ROM area from $F801 
to $F811, you would enter 


F801.F811 


(followed by [return], of course) and you would see the following values 
displayed (this is called a “hex dump’): 


F861- 868 26 47 F8 28 AQ OF 
F808- 909 B02 69 EB 8S 2E Bi 26 
F818- 45 38 


After the first line, where only those bytes up to the edge of the next 8-byte 
boundary are displayed, eight bytes will be displayed per line until the very 
last line where the last few remaining bytes are displayed. The two-digit 
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values after the dash in each line represent the bytes stored at the address 
displayed immediately before the dash and in succeeding memory locations. 


The STORE Command : Changing the Contents of 
Memory 


It is often handy to be able to quickly enter data into memory locations. 
You may want to do this in order to provide data to a program, to enter the 
program itself, or to make quick changes to the program. The system monitor 
makes this easy by providing you with a convenient command to do this. 


To change the contents of memory, you must first type in the address of the 
first location to be changed, followed by the STORE command (a colon), and 
then the values of the bytes to be stored in that location and succeeding 
locations, separated by spaces. For example, to place the values $3E, $22, 
$24, $00, and $29 into addresses $300 through $304, you would enter the 
command: 


300:3E 22 24 8 29 


(The number of bytes that can be stored after the colon is limited by the 
fact that only 255 characters can be entered before pressing [return] or else 
the line will be cancelled. This allows about 83 data bytes to be specified.) 


To continue entering values at this point, you can simply type a colon 
followed by more data bytes separated by spaces. The address at which the 
first byte will be stored will automatically be assumed to be the one after the 
last one that was accessed. Thus, if you entered the command 


744 33 


immediately after entering the above command, address $305 would contain 
$44 and address $306 would contain $33. 


All of the machine language programs that will be presented in this book 
can be entered using this technique. To understand how to do this, first refer 
to Table 3-2, which sets out the assembler source listing of an example pro- 
gram after the assembly process has been completed. This program doesn't 
do anything really useful, it just prints out all digits from @ to 9 on the video 
screen and then stops. What we are really interested in is seeing how to 
interpret this listing and how it can be used to allow you to enter the program 
into memory. 

First remember that the assembler-listing format used in this book is that 
used by the Merlin Pro assembler only and that if you are using any other 
assembler the format may be different. Fortunately, however, formats from 
one assembler to another are generally quite similar. 


The assembler-listing format is made up of six general fields. The first field 
is the address and data field and can be found at the far left of the listing. 
Each line in this field contains an address used by the program followed by 
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the data byte stored at that address and, in certain cases depending on the 
type of instruction, at the following one or two addresses as well. This infor- 
mation is all you need to be able to enter the program from the monitor 
because it is in exactly the same format used by the STORE command. To 
enter the program, all you must do is enter the following STORE commands: 


308:A2 Q 
302:8A 

303:9 BO 
385:28 ED FD 
308:E8 
309:E@ A 
30B:D@ FS 
30D:68 


Since the program is so short, you could also enter the whole program using 
just one long STORE command: 


300:A2 @ 8A 9 BB 28 ED FD E8 EB A DB FS CB 


The rest of the fields in the listing simply relate to the source code that gave 
rise to the machine language bytes that make up the program. These are, in 
order, the line number field, the label field, the instruction field, the operand 
field, and the comment field. 


A faster way to enter a machine language program that is already stored 
on diskette is, of course, to use the ProoDOS BLOAD command. This is done 
by entering the command 


BLOAD FILENAME ,Aaddr 


where “FILENAME” represents the name of the binary file to be loaded and 
‘‘addr”’ represents the decimal starting address at which it is to be loaded, or, 
if the address is preceded by “$’’, the hexadecimal starting address. The 
“ Aaddr” suffix is optional; if the suffix is omitted, the program will be loaded 
at the position it was in when it was originally saved to diskette using the 
BSAVE command. 


The MOVE Command : Copying the Contents of 
Memory 


It is sometimes necessary to copy the contents of one block of memory to 
another part of memory. Two common situations where such a move would 
be performed are when an assembly-language program is being relocated or 
when a data block is being duplicated because it may be overwritten by 
subsequent operations and you don’t want to lose it. 


You could perform the move by examining the contents of all the memory 
locations in question and then entering these values at the new locations 
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using the DISPLAY and STORE commands, but there is an easier way: you 
can use the MOVE command. The syntax of this command is as follows: 


{destination}<{sourceS}.{sourceE}M 


where {destination} represents the address to which the block of memory is 
to be moved (the destination address), {sourceS} represents the starting address 
of the block to be moved (the source starting address), and {sourceE} repre- 
sents the ending address of the block to be moved (the source ending address). 


For example, to move the program that you just entered in the previous 
section, which resides from $300 through $30D, to locations $1000 through 
$100D, you would enter the command 


1908<380.38DM 


To see that the move has, in fact, been performed, enter the following two 
commands: 


360.30D 
1009.1@808D 


and compare the two hex dumps. They will be identical apart from the address 
indicators. (You can also use the VERIFY command to do the comparison 
automatically; see below.) 


When moving a block of memory, you must ensure that the destination 
address is not within the range of addresses defined by the source block. If it 
is, then the block will not be properly moved because the area of the source 
block from the destination location to the end of the block will be overwritten 
before it is actually moved. This occurs because the byte stored at the lowest- 
addressed location in the source block is moved first, followed by the rest of 
the bytes in increasing order of address until the end of the block is reached. 
For example, if the MOVE command 


381<38098.38DM 


is entered, the block of memory from $301 to $30E will not contain an image 
of $300 to $30D before the move but rather will be filled with the value of the 
byte stored at $300. You can see why by visualizing the steps that are followed 
to perform the move: first, the byte at $300 is moved into $301, then the byte 
at $301 (which has just been overwritten) is moved into $302, and so on. This 
type of move is handy for quickly storing the same values at locations through- 
out an area of memory, but not much else. For example, to zero the area of 
memory from $2000 to $3FFF, you would enter the commands 


2000:9 
2081<2000.2FFEM 


One important note on using the MOVE command to relocate machine 
language programs: many programs will not operate properly at their new 
locations unless they are modified first. Any program that uses JMP (jump) 
or JSR (jump-to-subroutine) instructions to transfer control to areas that are 
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within the block being moved, or that read from or write to addresses within 
that block, fall within this “unrelocatable”’ category. This problem arises 
because such instructions refer to absolute memory locations, locations that 
will not be meaningful after the program has been moved. The easiest way to 
make a program operate at a new location is to reassemble it at the new 
location and then enter the new data bytes that the assembler generates. This 
can be done by changing the operand of the ORG (for “‘origin’’) statement in 
the assembler source listing (see line 7 of the sample program in Table 3-2) 
to reflect the new starting address of the program. You could also patch the 
program manually to fix up all such absolute references in the program by 
replacing them with the new absolute addresses (low-order byte first), but 
this is time consuming and prone to error. 


The VERIFY Command : Comparing Ranges of 
Memory 


Another useful chore that can be performed by the system monitor is the 
comparison of the contents of two blocks of memory. Comparisons are com- 
monly made for the purposes of determining the locations at which two 
similar programs (usually related revisions) differ from one another. 


You could perform the comparison manually by repeatedly using the DIS- 
PLAY command but this would be tedious at best, especially for long data 
blocks. The process can be automated, however, by using the VERIFY com- 
mand. The syntax for this command is as follows: 


{block2}<tblockS}.f{blockE}V 


where {block2} represents the starting address of the block of memory to 
which comparisons will be made, {blockS} represents the starting location of 
the main block, and {blockE} represents the ending location of the main block. 
When the command begins to execute, each byte in the main block will be 
compared with its corresponding byte in the other block. If there are any 
differences, then they will be printed out in the following format: 


faddress}-34 (CEA) 
where {address} is the address of the byte in the main block that is different, 


the first (unbracketed) data byte represents the value of that byte in the main 


block and the second number represents the value of that byte in the other 
block. 


The EXAMINE Command : Examining the 65C02’s 
Registers 


The system monitor reserves several locations in zero page for temporary 
storage of the 65C@2's internal registers, A, X, Y, P, and S. All of these registers 
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(except for the stack pointer, S) are loaded with the values stored at these 
locations whenever the monitor’s GO command is entered (see below). This 
allows you to properly initialize the 65C@2 registers before executing any 
assembly-language program. 


The saved contents of the 65CQ@2’s internal registers can be examined at any 
time by using the EXAMINE command by entering the following control 
character: 


Ccontrol-E] 


(Recall that this notation means ‘“‘press the CONTROL key and, while it is 
being held down, press the E key.”’) When the EXAMINE command is entered, 
the currently saved values of each of the five 65C@2 registers will be displayed 
in the following typical format: 


A=82 X=CC Y=D8 P=0@9 S=B/7 


In this list, A represents the accumulator, X and Y represent the X and Y 
index registers, P represents the processor status register, and S represents 
the stack pointer. The two-digit hexadecimal number after each “equal” sign 
indicates the current value of the corresponding register. 


Immediately after the [control-E] command has been entered and the con- 
tents of the registers have been displayed, you can set any of the register 
locations to any value that you want by entering a colon followed by the new 
values for the contents of the registers, separated by spaces. The new values 
must be entered in the order in which the registers are displayed. If you want 
to change some, but not all, of the registers, then you will have to enter the 
current values for those of the other registers that are displayed before the 
last one that you wish to change. 


For example, if you want to set the X register to $33 and leave the other 
registers unchanged, you would enter the command 


©82 33 


where @2 represents the current value of the accumulator. 


The [control-E] command is primarily used as a débugging tool when 
developing an assembly-language program. Program subroutines that require 
certain registers to be initialized in certain ways before they will perform 
properly can easily be tested by setting up the registers after entering [control- 
E]} and then executing the subroutine. 


The GO Command : Running a Program 


You can run any machine language program that is contained in memory 
by using the monitor’s GO command. To do this, you must type in the starting 
address of the program followed by “G’” and then press [return]. Before 
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control is passed to the program, the 65C@2’s A, X, Y, and P registers are 
loaded with the values last set by the EXAMINE command (see above). When 
the program stops running, you will usually return to the system monitor 


ved? 


command interpreter and see the “*’’ prompt symbol once again. 


For example, if you want to run a program that starts at location $300, then 
you would enter the command 


389G 


The LIST Command : Disassembling Assembly- 
Language Programs 


The LIST command can be used to translate bytes in any area of memory 
into the assembly-language mnemonics they represent and to display the 
listing on the screen. This command essentially reverses the process per- 


formed by an assembler and so the function it performs is called “disassem- 
bly.” 


A disassembled listing of memory is much more comprehensible and infor- 
mative to a programmer than a simple hex dump that only displays raw 
numbers. It is especially useful as an aid in debugging assembly-language 
programs that have been loaded into memory. The syntax associated with 
the LIST command is as follows: 


{address}L 


where {address} represents the address at which you want to begin the listing. 
A total of twenty disassembled lines will be displayed for each ‘‘L”’ specified 
after the address. 


Let’s examine an area of the //c’s system monitor ROM to observe the format 
in which the LIST command generates its output. As we will see later, the 
basic character input routine used by the Monitor begins at location $FDOC 
and is called RDKEY. To disassemble the RDKEY subroutine, enter the 
command 


FD@CL 

and you will see the following 20-line display: 
FD@C- A4 24 LDY $24 
FD@E- B1 28 LDA ($28),Y 
FD1@- EA NOP 
FD11- EA NOP 
FD12- EA NOP 
FD13- EA NOP 
FD14- EA NOP 


FD1S- EA NOP 
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FDI6- EA NOP 

FD17- EA NOP 

FD18- 6C 38 00 JMP ($8038) 
FDIB- 91 28 STA €$28),Y 
FDID- 28 4C CC JSR $CC4C 
FD20- 28 708 CC JSR $CC7@ 
FD23- 10 FB BPL $F D290 
FD25- 48 PHA 

FD26- AS 88 LDA #$08 
FD28- eC FB 64 BIT $O04FB 
FD2B- D@ 1D BNE $FD4A 
FD2D- 68 PLA 


Each line in this listing represents a starting address, the machine language 
bytes representing the 65C@2 instruction opcode and its operand, the three- 
letter mnemonic for the instruction, and the formatted operand. Note that 
operands that have a ‘‘$”’ prefix represent an address and that those that have 
a“ #$” prefix represent immediate hexadecimal data. In addition, the operand 
after any branch instruction (BEQ, BNE, BPL, and so on) is the absolute 
address of the ““branched-to”’ location rather than the relative address of that 
location. The 65C@2 uses relative addresses only, but it is the absolute address 
that is usually more meaningful because it allows a programmer to more 
easily follow the flow of the program. 


Note that you can continue to disassemble twenty more lines beginning at 
the address immediately after the last disassembled byte by entering the “L’”’ 
command without an address. Multiple ‘“L’’s can also be entered to disassem- 
ble more than twenty lines at once; for example, ‘“LLLL” allows you to 
disassemble eighty consecutive lines. 


When you are disassembling an area of memory you may sometimes see a 
‘‘2??”’ indicator in the opcode field instead of a standard 65C02 mnemonic. 
The system monitor’s disassembler subroutine uses this triad of question 
marks whenever it is unable to convert the contents of memory into a valid 
65C@2 instruction. This might happen if you are attempting to disassemble 
an area of memory that contains program data or encoded text rather than 
instructions or if you begin disassembling in the ‘“‘middle”’ of an instruction 
(remember that 65C@2 instructions can be up to three bytes long). If you 
suspect that you have started in the middle of an instruction, try disassem- 
bling from a location that is one or two locations away from the original 
starting location. 


In many cases, a data area will erroneously be interpreted as a series of 
valid instructions by the disassembler. For example, a zeroed out data area 
would appear as a series of BRK instructions. This is because the machine 
language byte for BRK is 00. Such data areas are usually obvious, however, 


because the “program” they appear to define is clearly meaningless or out of 
context. 
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The NORMAL and INVERSE Commands : Changing 
Video Display Modes 


Monitor operations that affect the video display can be performed either in 
normal video (white characters on a black background) or in inverse video 
(black characters on a white background). To select the inverse video format, 
enter the command 


I Creturn] 
To select the normal video format, enter the command 


N Creturn] 


You will probably not have to use these commands very often. 


The ADD and SUBTRACT Commands : Simple 
Arithmetic 


You can perform simple one-byte hexadecimal arithmetic while in the 
system monitor by taking advantage of its ADD and SUBTRACT commands. 
To add two numbers together, you would enter the command 


{number1}+{numbere2} 


where {number1} and {number2} represent the two one-byte hexadecimal 
numbers to be added. The result of the addition will be shown on the next 
video display line. 

The subtraction command is similar. To subtract one number, say {number2}, 
from another, say {number1}, you would enter the command 


{number1}-{number2} 


and the result will be calculated and displayed. 


The result that either the ADD or SUBTRACT command displays is a one- 
byte number only. This means that any overflow or underflow in the arith- 
metic calculation is ignored. 


The BASIC and CONTINUE BASIC Commands : 
Entering Applesoft 


The system monitor supports two commands that can be used to transfer 
control from the monitor to Applesoft direct mode (as indicated by the “]”’ 
prompt symbol). These are the [control-B] and [control-C] commands. There 
are also subroutines that can be called to enter Applesoft that begin at $0000 
(with or without ProDOS) and $03D@ and $3D3 (only when ProDOS is being 
used). 
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The BASIC command, [control-B], is used to re-enter Applesoft in such a 
way as to cause it to be reinitialized. This is called a ‘“‘cold start” and will 
cause any Applesoft program which may be residing in memory to be removed. 


The CONTINUE BASIC command, [control-C], is used to re-enter Applesoft 
in such a way that the existing Applesoft program and the values of its 
variables are not affected at all. This is called a “warm start.’’ An alternative 
way to warm-start Applesoft is to call a subroutine that begins at $0000 by 
entering the command ‘0G’. 


The effect on the ProDOS disk operating system must also be considered 
when moving to Applesoft from the monitor. If you are using ProDOS and the 
monitor was entered with either a CALL —151 or CALL —155 command (the 
warm-start entry points), then ProDOS will still be active upon the return to 
Applesoft using [control-C]. The [control-B] command, however, will cause a 
NO BUFFERS AVAILABLE error message to be displayed whenever a ProDOS 
I/O command is attempted. This renders ProDOS useless and so you should 
never use {control-B] to return to Applesoft when ProDOS is active. 


If the monitor was entered via its cold-start entry point with a CALL —-167 
command, ProDOS will be deactivated after a [control-B] and [control-C] 
command is entered to cause a return to Applesoft. In this situation, ProDOS 
can be reactivated by entering a CALL 976 command, but this causes the 
values of any active Applesoft program variables to be cleared. Note, however, 
that even after the CALL 976 is entered, ProDOS will still be rendered unus- 
able if it was entered with a [control-B] command for the reasons given in 
the previous paragraph. 


Applesoft can always be entered with ProDOS active by using a “3DQG” 
command ($3D60 is the address of a subroutine that performs a warm start of 
ProDOS), but this method is not recommended because of zero page memory 
conflicts between ProDOS and the system monitor and the fact that any active 
Applesoft variables will be cleared. 


In summary, to ensure that you never deactivate ProDOS or clear the values 
of any active Applesoft program variables, you should always enter the mon- 
itor at one of its two warm-start entry points (-151 or —155) and always return 
to BASIC using the [control-C] command. 


The USER Command : User-Defined Command 


The system monitor is flexible enough to allow you to define the actions to 
be taken whenever its special USER command, [control-Y], is entered. The 
[control-Y] command causes the monitor to perform an unconditional jump 
to location $3F8. By placing a 65C@2 JMP instruction there (which behaves 
like an Applesoft GOTO), followed by the two-byte address (low byte first) of 
the start of the subroutine that you want to execute, you can easily make the 
[control-Y] command execute any program you wish. 


Let's take a look at a simple example of how to take advantage of the USER 
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command. The first thing you have to decide is what you want to happen 
when [control-Y] is pressed—that’s easy. Then you must write the program 
to perform what it is you want to do—not so easy. We can, however, make 
use of subroutines that already exist in the //c’s ROM areas to perform many 
useful chores. For example, there is a subroutine beginning at $FC58 that can 
be called to clear the video screen and a subroutine beginning at $FD@C to 
read a key from the keyboard. To set things up so that when the USER 
command is entered, the system pauses until a key is pressed and then clears 
the screen, a “JMP $0300” instruction must be set up at $3F8 and then “JSR 
$FDOC” and “JMP $FC58” instructions must be stored beginning at $300. 
This can be done by using two STORE commands as follows: 


3F8:4C 00 93 


(“4C”’ is the opcode for the JMP instruction and “00 @3” is the address of the 
user-defined subroutine—low-order byte first) and 


300:280 @C FD 4C 58 FC 


where ‘‘20 @C FD” are the data bytes for ‘JSR $FDOC’” ($20 is the opcode for 
the JSR instruction) and ‘4C 58 FC” are the data bytes for “JMP $FC58”. 
Now when you enter [control-Y] the //c will wait until you press a key and 
then the screen will be cleared! 


Note that you cannot simply place the entire subroutine at $3F8, because 
only locations $3F8 to $3FA are reserved for use by the USER command. 
Locations after that are reserved for other purposes and must not be over- 
written. 


Parameters can be passed to the USER command by storing them in mem- 
ory just before the monitor executes the USER command. This can be done 
by using the STORE command. If the parameters to be passed represent 
addresses, there is a much more convenient way to pass up to three of them. 
For example, if the USER command is entered as follows: 


addri<addre.addr3(control-Y] 


then “addr1”’ will be stored at monitor locations A4L ($42) and A4H ($43), 
“addr2” will be stored at A1L ($3C) and A1H ($3D), and “‘addr3” will be stored 
at A2L ($3E) and A2H ($3F). Each of these addresses is stored with its lower 
two digits in the first of the two memory locations specified for each param- 
eter. Two addresses can be passed (in A1L/A1H and A2L/A2H) by removing 
the “‘addr1<” part in the above command line and one address can be passed 
(in A1L/A1H) by removing the “addr1<addr2.” part. 


The KEYBOARD and PRINTER Commands : 
Redirecting Input and Output 


The system monitor provides two simple commands that allow you to easily 
redirect the source of character input and output to one of the //c’s built-in /O 
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ports (the printer, modem, 80-column display, mouse, or disk drive). These 
are the KEYBOARD, [control-K], and PRINTER, [control-P], commands, 
respectively. They perform exactly same the functions as Applesoft’s IN#¥ and 
PR# commands. 


The syntax associated with both of these commands is similar: 


{port number}{€control-K] 


for the KEYBOARD command and 


{port number}[control-P] 


for the PRINTER command, where {port number} is a digit which can take 
on the values 1 (printer port), 2 (modem port), 3 (8@-column video port), 4 
(mouse port), 6 (internal disk drive port), or 7 (external disk drive port) and 
represents the port number of the device to which you wish to pass control. 
You can also specify a slot number of @; if you do this when entering the 
KEYBOARD command, the keyboard will become the source of character 
information. If you do this when entering the PRINTER command, the video 
screen will become the current output device. 


The KEYBOARD command is usually used to “connect” alternate input 
devices such as an external keyboard or a modem to the //c by vectoring all 
requests for input to them. The PRINTER command is usually used to activate 
a printer so that you can obtain a hardcopy printout of your activities while 
in the monitor. To turn on a printer that is connected to port 1 (the //c’s 
standard printer port) you would enter the command 


1fcontrol-P] 


After this is done, all outputted characters will be sent to the printer instead 
of the video screen. 


Another common use for the PRINTER command is to “boot” the disk 
drive. This can be done by entering the command: 


6Ccontrol-P] 
Note that whenever the KEYBOARD or PRINTER command is entered, 


the monitor jumps to location $Cs@@ (where ‘‘s’’ is the port number specified), 
which is the first address of a driver program for the particular port in 
question. It is the driver program in ROM that dictates exactly how the I/O 


is to be redirected. 


I/O is redirected on the //c by changing the addresses stored in two vectors 
in zero page, the input link and the output link. The use of these links will be 
discussed in detail in Chapters 6 and 7. 


Note that because of the way ProDOS operates, the KEYBOARD and 
PRINTER commands may not work properly in a ProDOS environment. This 
is because ProDOS is forever storing the addresses of its own input and output 
subroutines in the I/O links; as soon as this is done, the new input or output 
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device is disconnected. Methods of avoiding these problems will also be 
discussed in Chapters 6 and 7. In summary, if ProDOS is active, then use its 
PR# and IN# commands while in the system monitor and not the monitor's 
KEYBOARD and PRINTER commands. 


Multiple Commands on One Line 


All of the examples that we have given so far have contained only one 
monitor command per line. The monitor is not fussy about this, however, and 
you can actually put as many commands on one line as that line can hold (a 
line must be less than 256 characters long). 


There are a few syntactical rules to follow, however. First of all, each 
command on the line must be separated from the next one by a space unless 
both adjacent commands are one of the letter commands (L, G, M, V, I, N), 
in which case they can be jammed together. 


Second, any command that immediately follows the data bytes after the 
STORE command must be a letter command without a preceding address. A 
convenient command to use for this purpose is the NORMAL command (‘‘N”) 
since it is really a ‘‘do-nothing”’ letter command. 


Let’s look at a few examples of multiple command entry to see how it works. 


1. 30@LLL will disassemble 60 lines of a program beginning at $300 at 
once. 


2. 300:4C 3A FF N 300G will enter a short program beginning at $300 to 
beep the speaker and then execute it (note the ‘‘N”’ after the data bytes 
of the STORE command). 


3. 300.326 860.830 will display two separate blocks of memory, $300 . . . $320 
and $800 .. . $830 one after the other. 


4. 3F8:4C 00 03 N 300:4C 58 FC N [control-Y] will set up the USER com- 
mand jump address, enter the program to be jumped to, and then execute 
the USER command (which causes the screen to clear in this example). 


system Monitor Subroutines 


As we have already seen, the system monitor is made up of several useful 
subroutines. Most of these subroutines can easily be accessed from Applesoft 
or assembly-language programs. 


Direct access from Applesoft is achieved by using the Applesoft CALL com- 
mand. Note, however, that only those monitor subroutines that require no 
initialization of the 65C@2 registers can be CALLed in this way because there 
are no Applesoft commands available to you to set up these registers directly. 
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One way to access subroutines that require register initialization would be 
to CALL a RAM-based program that would set up these registers explicitly 
and then call the requested subroutine. An alternative method makes use of 
the monitor's GO command and the fact that GO initializes the 65CQ2’s 
registers to the values stored in zero page by the EXAMINE command before 
control is passed to the subroutine whose address is stored at $3A and $3B 
(low-order byte first). The values of the registers A, X, Y, and P are stored at 
locations $45, $46, $47, and $48, respectively. To execute the subroutine, you 
must first use the Applesoft POKE command to store the address of the 
subroutine to be executed at $3A/$3B and to store the appropriate register 
values at locations $45—$48. The final step is to execute the GO command by 
entering it at the point where it sets up the registers before passing control 
to the address at $3A/$3B. This is location $FEB9 (65209). 


For example, you can set up a simple decimal-to-hexadecimal conversion 
program from Applesoft by calling a monitor subroutine called PRINTYX 
($F940). This subroutine prints out the Y and X registers as four hexadecimal 
digits (the two most-significant digits are held in Y). To get the converter to 
work, all you have to do is take your decimal number, divide it by 256, and 
put the quotient in Y (this represents the decimal value of the two high-order 
digits) and the remainder in X (this represents the decimal value of the two 
low-order digits). Here is an example of such a program: 


1080 DEF FN MDCZ) = 2 - 256 * INTCZ / 256) 

110 INPUT “ENTER A NUMBER: "3;N 

128 ADDR = 638898 : REM ADDRESS OF “PRINTYX" 
C$F 940) 

138 POKE 78,FN MDCN):REM SET UP "*X" 

148 POKE 71,INT CN/256):REM SET UP "Y"™ 

15@ POKE 58,FN MDCADDR) : REM SET UP ADDR LOW 

168 POKE S9,INT CADDR/256) : REM SET UP 
ADDR HIGH 

178 CALL 65209 REM CALL "GO" AT $FEB9 


Line 100 in this program defines a “modulo 256” function that can be used 
to calculate the decimal value of the lower two digits of a hexadecimal number 
(@...255). 


These complications do not really arise when calling monitor subroutines 
from an assembly-language program because the 65C@2 has explicit com- 
mands for initializing registers (LDA, LDX, LDY, and soon). Once the registers 
have been properly set up, you can execute the subroutine by using a JSR 
instruction (like an Applesoft GOSUB) or a JMP instruction (like an Applesoft 
GOTO). 


Some of the more useful subroutines available in the system monitor are 
set out in Table 3-3. These subroutines are presented in increasing order of 
address and a symbolic name for each address is shown immediately after 
the address. 
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Table 3-3. Apple //c system monitor subroutines. 


Address 
Hex (Dec) 
$F940 (63808) 
$FBIE (64286) 
$FBC1 (64449) 
$FC22 (64546) 
$FC42 (64578) 
$FC58 (64600) 
$FC62 (64610) 
$FCIC (64668) 


Symbolic Name 
PRINTYX 


PREAD 


BASCALC 


VTAB 


CLREOP 


HOME 


CR 


CLREOL 


Description 


Prints out the number held in X (low) 
and Y (high) as four hexadecimal 
digits. 


Reads the current value of the game 
controller input. On entry, X = game 
controller number (@ or 1). On exit, 
Y=game controller reading 
(@...255) and A is destroyed. 


Calculates the address of the first 
location used by the current video 
line. On entry, A= video line number 
(0...23). On exit, the address is 
stored in BASL ($28) and BASH ($29), 
low byte first, and A is destroyed. 


Moves the cursor to the video dis- 
play line indicated by CV ($25). On 
entry, CV must contain the line num- 
ber required (0... 23). On exit, the 
base address for the line is set up in 
BASL ($28) and BASH ($29) and A is 
destroyed. 


Clears the screen display from the 
current cursor position to the end of 
the screen without changing the 
position of the cursor. On exit, A and 
Y are destroyed. 


Clears the screen display and posi- 
tions the cursor at the left of the first 
line on the screen. On exit, A and Y 
are destroyed. 


Moves the cursor to the first position 
of the next video display line (and 
scrolls if required). On exit, A and Y 
are destroyed. 


Clears the screen display from the 
current cursor position to the end of 
the line without changing the cursor 
position. On exit, A and Y are 
destroyed. 


(continued) 
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Table 3-3. Apple //c system monitor subroutines (continued). 


Address 
Hex (Dec) 
$FCA8 (64680) 
$FDOC (64780) 
$FD1B (64795) 
$FD35 (64821) 
$FD6A (64874) 
$FDDA (64986) 


Symbolic Name 
WAIT 


RDKEY 


KEYIN 


RDCHAR 


GETLN 


PRBYTE 


Description 


Causes a delay of 
@.5*(26+27*A+5*A*A) microse- 
conds. On exit, A is destroyed. 


Receives a character of information 
from the currently active input device 
(the address for the input subroutine 
for this device is held in KSWL ($38) 
and KSWH ($39)). On exit, A con- 
tains the inputted character and Y 
is destroyed; other registers may be 
destroyed, depending on the input 
subroutine for the input device. 


Receives a character of information 
from the keyboard. On exit, A con- 
tains the inputted character and Y 
is destroyed. 


Receives a character of information 
from the currently active input device 
and enables escape sequences. On 
exit, A contains the inputted char- 
acter and Y is destroyed; other reg- 
isters may be destroyed, depending 
on the input subroutine for the input 
device. 


Receives a line of information (ter- 
minated by [return]) from the cur- 
rently active input device and places 
it into the input buffer at 
$200 ...$2FF. On entry, the prompt 
symbol to be used must be stored in 
PROMPT ($33). On exit, the line is 
stored in the input buffer beginning 
at $200, X contains the number of 
characters in the line, and A and Y 
are destroyed. 


Displays a byte as two hexadecimal 
digits. On entry, A contains the byte 
to be displayed. On exit, A is 
destroyed. 


(continued) 
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Table 3-3. Apple //c system monitor subroutines (continued). 


Address 
Hex (Dec) Symbolic Name Description 
$FDED (65005) COUT Sends a character of information to 


the currently active output device 
(the address for the output subrou- 
tine for this device is held in CSWL 
($36) and CSWH ($37)). On entry, A 
contains the byte to be sent. On exit, 
registers may be destroyed, depend- 
ing on the output subroutine for the 
output device. 


$FDFO (65008) COUT! Displays a character of information 
on the video display screen at the 
current cursor position. The display 
mode is set by logically ANDing the 
byte with INVFLG ($32). On entry, 
A contains the byte to be displayed 
(with its high bit set to one). On exit, 
all registers are preserved. 


$FF69 (65385) MONZ Enters the //c’s system monitor. On 
exit, all registers are destroyed. 


Table 3-3 by no means represents a complete list of the monitor’s subrou- 
tines. To examine all the subroutines for yourself, you should consult Apple's 
published source listing of the monitor ROM in ‘‘The Apple //c Reference 
Manual’, Volume 2. 


Further Reading for Chapter 3 


On system monitor subroutines ... 
The Apple //c Reference Manual, Volume 2, Apple Computer, Inc., 1984. 
This manual contains the source code for the system monitor on the //c. 


W.E. Dougherty, The Apple II Monitors Peeled, Apple Computer, Inc., 1981. 
A detailed look at the system monitors for the Apple II and Apple II Plus. 


Applesoft BASIC 


Applesoft BASIC is a high-level programming language interpreter that 
occupies 10K of the //c’s ROM space from location $D000 through location 
$F7FF. (BASIC is an acronym for Beginner’s All-Purpose Symbolic Instruction 
Code.) It is yet another version of the “basic’” BASIC developed by Microsoft 
Corporation of Bellevue, Washington, and so is structurally similar to Micro- 
soft-developed BASICs running on many other personal computers, including 
those manufactured by Tandy/Radio Shack, Commodore, and IBM. 


The //c version of Applesoft is slightly different from the one used on the 
Apple //e, Apple II Plus, and Apple II. The major changes that have been made 
are as follows: 


@ The Applesoft cassette tape commands are accepted but are treated just 
like the & (ampersand) command. These are the SHLOAD, RECALL, 
STORE, LOAD, and SAVE commands. 


@ Applesoft commands can be entered in upper- or lowercase. 


@ Program lines are listed on the screen beginning in column two in order 
to facilitate screen editing. (When you move the cursor up to edit the 
line, it is now positioned over the first digit in the line number.) 


@ The low-resolution graphics commands have been modified in order to 
support the //c’s special double-width low-resolution graphics display 
mode. (See Chapter 7.) 


Fortunately, none of these changes should affect the performance of the 
vast majority of programs written for the previous version of Applesoft. 


What exactly is the Applesoft programming language, anyway? Well, it’s 
really just another 65C02 assembly-language program, but one that has a 
special goal: to allow you to easily write your own programs using straight- 
forward, English-like commands. These commands can be used in such a way 
as to allow you to manipulate various types of data and to perform input/ 
output functions. In addition, Applesoft comes with a built-in editing envi- 
ronment that facilitates creation of its programs. 


Applesoft is actually a language “interpreter” and a program is simply a 
set of data that the Applesoft code in ROM is continuously analyzing (inter- 
preting) to determine what commands are to be executed and in what order. 
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Other types of BASICs, called ‘‘compilers,”’ are also available. Compilers are 
simply preprocessors that convert your program source code into directly 
executable machine language that can then be run just like any other machine- 
language program. Since directly executable code is generated, no interpre- 
tation is necessary when the code is actually executed (except, of course, by 
the microprocessor) and so the program will run much faster than its inter- 
preted counterpart. Although Applesoft compilers are available, none have 
been officially released by Apple itself. 


The purpose of this chapter is not to teach you how to program in the 
Applesoft language. In fact, you will be presumed to be familiar with Applesoft 
already. What we are going to do is take a close look at the internals of 
Applesoft to see how the interpreter performs its various duties. This will 
include a look at how an Applesoft program and its variables are stored and - 
arranged in memory and how the program is actually executed by the Apple- 
soft interpreter. We will also take a look at how Applesoft can be linked to 
machine-language subroutines to improve program speed and efficiency. 


The study of the internal structure of Applesoft is difficult and frustrating 
because no official source listing for its code has been made available by 
Apple. Such a study is not totally futile, however, because it is possible to 
disassemble the contents of the Applesoft ROM (using the monitor's “L” 
command or some other disassembler) to view the language in a convenient 
assembler-language form that can sometimes be made intelligible (if you're 
lucky). In addition, at least two ‘“‘unofficial” source listings of Applesoft have 
been published (see the references at the end of this chapter). 

Knowledge of the internal structure of Applesoft is important for three 
main reasons. First, by analyzing the work of the professional programmers 
who wrote the language you might develop better personal programming 
practices. Second, you can generally write much more elegant and efficient 
assembly-language routines to be used in conjunction with Applesoft pro- 
grams if the routines use the standard routines found in Applesoft because 
this spares you from having to redevelop the same code from scratch. Third, 
it is possible to write much more efficient Applesoft programs if you under- 
stand how they are being executed. 


Applesoft Memory Map 


The Applesoft interpreter in ROM uses most of the RAM space located from 
$0000 to $95FF in the main memory area of the //c for program and variable 
storage and for work areas. (The //c’s other memory area, ‘‘auxiliary’’ memory, 
will be discussed in Chaper 8.) The area of RAM memory above this, from 
$9600 to $BFFF, is reserved for use by BASIC.SYSTEM (a ProDOS/Applesoft 
interface program) and the ProDOS disk operating system itself. (See Chapter 
5). As we will see in Chapter 5, ProDOS actually ‘‘steals” space from Applesoft 
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when disk files are opened, but this is done in such a way that the operation 
of the Applesoft program is not disturbed. 


Much of the 65C@2 zero page ($0000 . . . $@OFF) is used by Applesoft to hold 
short subroutines, temporary data areas, and several two-byte pointers that 
contain the addresses of important data areas used by the program. For 
example, there are pointers that hold the starting and ending addresses of the 
program itself, of the space reserved for simple variables and array variables, 
and of the space reserved for string data. We'll be looking at these pointers in 
greater detail later on in this section. 


(To review, a pointer is a pair of bytes that are positioned in adjacent 
memory locations and that contain the base address of an area in memory to 
which they are said to be pointing. The lower half of this address is stored in 
the byte that is lower in memory. To calculate the absolute address of the 
area being pointed to, take the number held in the first location and add it to 
256 times the number in the second location.) 


Page one of memory ($100 ...$1FF) is implicitly used by Applesoft since 
the 65C@2 microprocessor uses this page as its stack. In addition, Applesoft 
uses the stack area for temporary storage of information when it executes 
instructions such as FOR/NEXT, GOSUB/RETURN, and ONERR GOTO that 
need space to hold transfer-of-control information and when it converts binary 
numbers into decimal numbers. 


Applesoft uses page two of memory ($200... $2FF) as its character input 
buffer. For example, whenever an Applesoft program executes the INPUT 
command to read a line from the keyboard, it initially stores the response in 
this buffer and then processes it and moves it up into a space reserved for 
string data near the end of the RAM space reserved for use by Applesoft. 


The lower part of page three of memory from $300 . . . $3CF is not used by 
Applesoft and so is a good place to store short assembly-language programs 
or other data. However, the entire upper part of this page, from $3D0.. . $3FF, 
is reserved for use by ProDOS, the system monitor (to hold the USER vector 
and the 65C02 RESET, IRQ, NMI, and BRK interrupt vectors), and by Apple- 
soft. Applesoft reserves the three bytes beginning with $3F5 for use with its 
& (ampersand) command. Thus, the upper part of page three should not be 
overwritten unless it is for the specific purpose of modifying the information 
stored there. Appendix IV contains a complete memory map of the area in 
page three from $3D0...$3FF. 


Pages four through seven ($400 . . . $7FF) are used for the //c’s primary text 
display screen. (A secondary text display screen can also be enabled that uses 
pages eight through eleven ($800 . . . $BFF), but it is rarely used.) See Chapter 
7 for more information on how the //c interprets these pages. 


The rest of the RAM space, from $800 up to $95FF, is usually available for 
storage of the Applesoft program itself and of any variables that it may use. 
Figure 4-1 shows a generalized Applesoft memory map that indicates the 
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$BFFF 
ProDOS 


$BFOO 
BASIC. SYSTEM 


SET BY 
HIMEM: (USUALLY MEMSIZ ($73) 
$9600) STRING DATA | 
FRETOP ($6F) 
FREE SPACE 
$6000 
HIGH-RES 
PAGE 2 
$4000 
HIGH-RES 
PAGE 1 
$2000 
FREE SPACE 
STREND 
ARRAY (S6D) 
VARIABLES 
ARYTAB ($6B) 
SIMPLE 
SET BY VARIABLES 
LOMEM: 


VARTAB ($69) 
PRGEND (SAF) 


FREE SPACE 


TOKENIZED | 


APPLESOFT 
PROGRAM 


$0801 TXTTAB ($67) 
Figure 4-1. Applesoft memory map and data pointers. 


relative positions of the program and its variable spaces. The pointers to these 
areas are all held in zero page and are summarized in Table 4-1. 


The Applesoft program itself is usually stored beginning at location $801, 
which is the default value of TXTTAB ($67), the start-of-program pointer. The 
byte stored at the location immediately before this location (usually $800) 
must always be zero. The space used to store information relating to program 
variables usually starts immediately after the end of the program at the 


Table 4-1. Applesoft pointer locations. 


Pointer Location 


Hex 


$67 
$68 


$69 
$6A 


$6B 
$6C 


$6D 
$6E 


$6F 
$70 


$73 
$74 


$AF 
$BO 


(Dec) 
(103) 
(104) 


(105) 
(106) 


(107) 
(108) 


(109) 
(110) 


(111) 
(112) 


(115) 
(116) 


(175) 
(176) 


Symbolic Name 
TXTTAB _ (low) 
(high) 
VARTAB _ (low) 
(high) 
ARYTAB _ (low) 
(high) 
STREND _ (low) 
(high) 
FRETOP (low) 
(high) 
MEMSIZ _— (low) 
(high) 
PRGEND (low) 
(high) 
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Description 


Start of Applesoft program (nor- 
mally $801). 


Start of simple variable space. This 
space usually begins right after the 
end of the program. However, it 
can be set higher by using the 
Applesoft LOMEM: command. 


Start of array space. This space 
begins right after the end of simple 
variable space. 


End of variable space. 


Start of string space. Applesoft 
strings are stored from here to just 
before the address pointed to by 
MEMSIZ ($73). 


End of string space plus 1 and last 
location available to Applesoft plus 
1. Applesoft strings are stored from 
this locations down to FRETOP 
($6F). This location is usually $9600 
(when using ProDOS) but can be 
set lower by using the Applesoft 
HIMEM: command. 


End of Applesoft progam plus 1 or 
2. The end of an Applesoft program 
is signified by three consecutive “0” 
bytes. The first “@”’ is the end-of- 
line marker for the last line in the 
program and the next two ‘‘@’’’s 
are the ‘‘address”’ of the next line. 


location pointed to by VARTAB ($69), the start-of-simple-variables pointer. 
The position of the start of variable space, however, can be selected by using 
the Applesoft LOMEM: command before any variables have been defined in 
the program. This allows you to create a free space between the end of the 
program and the beginning of the variables that will not be overwritten and 
that could be used to hold, for example, a machine-language subroutine that 
is called by the Applesoft program. 
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Applesoft supports two fundamental classes of variables: array variables 
and simple variables. Array variables can hold real numbers, integer num- 
bers, or strings; simple variables can hold any of these three types of variables 
and a special function variable as well (more on this later). An array variable 
is one that is a member of a collection of variables that are referred to by the 
same name but that are distinguished from one another by specifying a 
subscript for each dimension of the array. For example, the variable AB(3,4,2) 
is the “3,4,2”° element of a three-dimensional array called ‘“‘AB’’. A simple 
variable is simply one that is not an element of such an array and that is 
specified by name only and not by a subscript. 


Applesoft keeps information relating to simple variables in a contiguous 
block of memory that begins at the address pointed to by VARTAB ($69) and 
ends at the address just before the one pointed to by ARYTAB ($6B). Infor- 
mation relating to array variables begins at the address pointed to by ARYTAB 
and ends at the address pointed to by STREND ($6D). 


After the end of the array variable space comes a free space that ends at the 
address pointed to by FRETOP ($6F), the start-of-string-space pointer. Gen- 
erally speaking, the contents of string variables are stored from here to the 
highest available location in memory (usually $95FF). The MEMSIZ ($73) 
pointer contains this address plus 1. Strings grow down in memory, so that 
when more strings are defined, they are placed in memory just below the 
value contained in FRETOP and then FRETOP is reduced by the length of the 
string. 


The value of MEMSIZ can be lowered by using the Applesoft HIMEM: 
command. This is usually done to provide a safe area for the storage of 
machine-language programs (we'll present the details of how to do this in 
Chapter 5), but it is also commonly done to avoid storing variable data within 
either of the //c’s two 8192-byte high-resolution graphics screen areas (if this 
happens, the data will likely be destroyed when a graphics command is 
executed). These two areas are located from $2000...$3FFF and from 
$4000 ... $5FFF. For example, to “protect’’ the first high-resolution graphics 
screen, you would enter the command HIMEM:7168. This sets MEMSIZ to 
1024 bytes below the start of the graphics screen memory area ($2000-$400 
is equal to 7168 decimal). You can’t just set HIMEM: to 8192 ($2000) because 
ProDOS uses the 1024 bytes above HIMEM: as a general purpose file buffer. 
(See Chapter 5.) 


Note that the free space between the end of the array variables and the 
beginning of the string data will become smaller and smaller as more vari- 
ables are defined and as more strings are defined. When all of the free space 
has been used up, an OUT OF MEMORY error message will be generated. 


In the next few sections, we will discuss the data spaces used by Applesoft 
in greater detail. 
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Tokenization of Applesoft Programs 


An Applesoft program is simply the data the Applesoft interpreter acts on 
in order to determine exactly what instructions it is to execute and in what 
order. This data is put into memory with a LOAD or RUN command or is 
simply typed in from the keyboard. 


You might think that an Applesoft program is stored in memory in exactly 
the same format in which it is displayed when it is listed. To save valuable 
memory space (an Applesoft program and its variables cannot use up more 
than about 36,000 bytes when ProDOS is being used), and to speed up program 
execution, however, each line of an Applesoft program is analyzed and com- 
pressed before it is actually inserted into the proper area of memory. This 
process is called “tokenization” because it involves, among other things, 
substituting one-byte tokens for Applesoft keywords. For example, if you enter 
the line 


180 HGRe 


it is not stored as nine bytes in memory as it would be if you used a standard 
line editor to create the source file (eight bytes of text plus one byte for the 
carriage return that follows the line). Rather, it is stored as six bytes: two for 
the line number, one for the token for the HGR2 keyword, and three for 
overhead information (these overhead bytes will be described below). 


It is the tokenized program that is analyzed by the Applesoft interpreter 
and not the original source listing. By the way, listing a program is the same 
as ‘‘detokenizing’’ it because the LIST command essentially converts tokens 
back into their full keywords. 


Let’s take a detailed look at what happens when you add a new line to an 
Applesoft program while in direct mode (that is, when the program is not 
running and the “‘]”” prompt symbol is being displayed). 


When you type in a line of characters (each line can be up to 239 characters 
in length) and then press the [return] key to enter it, Applesoft scans the input 
line and checks to see whether it begins with a valid line number. If it doesn't, 
then Applesoft thinks that this is a direct command and attempts to execute 
it right away; if it does begin with a line number, then Applesoft usually 
interprets it as a deferred command (that is, one that is to be executed only 
when the program is executed) and will tokenize it and store it in the proper 
position in memory. However, if a valid line number is entered by itself, the 
Applesoft interpreter will delete that line in the program. 


The line is placed in memory in such a way that the ascending numeric 
sequence of the line numbers in the program is maintained. The lowest- 
numbered line is stored lowest in memory at the location pointed to by the 
beginning-of-program pointer, TXTTAB ($67), and the higher-numbered lines 
are stored sequentially upward in memory. 
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The bytes that make up a tokenized line are arranged in memory as follows: 


xx yy xx yy XX yy 22 ... 89 
address this tokens and ASCII end of 
of next line characters for the line 

line number contents of line marker 


The “address of next line’ and ‘‘this line number” fields are stored as two 
bytes, with the least-significant byte coming first. The three bytes of overhead 
that were mentioned above are made up of the two bytes allocated for the 
address of the next line and the 00 byte that marks the end of the line. 


Keyword Tokens 


We will now take a closer look at what the tokenized part of the line (the 
part between the line number and end-of-line marker) looks like. We will 
begin with a description of the tokens used to replace the Applesoft keywords 
in a program line. These keywords represent the Applesoft commands, func- 
tions, and mathematical and logical operators. 


Each Applesoft keyword is assigned by the interpreter toa one-byte quantity 
called a token. This is done for two main reasons: first, to conserve memory 
space and, second, to improve the execution speed of the program. 


The tokens that Applesoft assigns to each of its keywords are presented in 
Table 4-2 together with the addresses of the subroutines within Applesoft that 
are used to deal with the keyword command or function that they represent 
(where applicable). You will notice that all of these tokens are greater than 
or equal to $80. If the tokenized part of a program line contains bytes that 
are less than $80, then these bytes are simply the ASCII codes for the char- 
acters that were typed in when the line was entered. (See Appendix I for the 
ASCII codes used to represent characters.) This will include all digits (other 
than those entered for the line number), all text between quotation marks 
after PRINT, DATA, and REM statements, and all characters used to represent 
variable names. 


Before you get hopelessly confused, let’s look at an example. From Applesoft 
direct mode, enter NEW, and then enter the following line: 


108 PI = 4 * ATN (1): PRINT “PI = “3PI: END 


The bytes used to store this line in memory are as follows: (You can see 
these bytes for yourself by first entering CALL —151 to enter the system 
monitor, and then entering 801.81C to display the first few bytes of the 
program. As we Saw earlier, an Applesoft program is usually stored in memory 
beginning at location $801.) 
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Table 4-2. Applesoft keyword tokens. (continued) 


Token 


$80 
$81 
$82 
$83 
$84 
$85 
$86 
$87 
$88 
$89 
$8A 
$8B 
$8C 
$8D 
$8E 
$8F 
$90 
$91 
$92 
$93 
$94 
$95 
$96 
$97 
$98 
$99 
$9A 
$9B 
$9C 
$9D 
$9E 
$9F 
$AQ 
$A1 
$A2 
$A3 
$A4 
$A5 
$A6 
$A7 
$A8 
$A9 
$AA 
$AB 
$AC 


Keyword 


END 
FOR 
NEXT 
DATA 
INPUT 
DEL 

DIM 
READ 
GR 

TEXT 
PR# 

IN# 
CALL 
PLOT 
HLIN 
VLIN 
HGR2 
HGR 
HCOLOR= 
HPLOT 
DRAW 
XDRAW 
HTAB 
HOME 
ROT= 
SCALE= 
SHLOAD 
TRACE 
NOTRACE 
NORMAL 
INVERSE 
FLASH 
COLOR= 
POP 
VTAB 
HIMEM: 
LOMEM: 
ONERR 
RESUME 
RECALL 
STORE 
SPEED = 
LET 
GOTO 
RUN 
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Address of 
Subroutine 


$D870 
$D766 
$DCF9 
$D995 
$DBB2 
$F331 
$DFD9 
$DBE2 
$F390 
$F399 
$FIES 
$F1DE 
$F1D5 
$F225 
$F232 
$F241 
$F3D8 
$F3E2 
$F6E9 
$F6FE 
$F769 
$F76F 
$F7E7 
$FC58 
$F721 
$F727 
$03F5 
$F26D 
$F26F 
$F273 
$F277 
$F280 
$F24F 
$D96B 
$F256 
$F286 
$F2A6 
$F2CB 
$F318 
$03F5 
$03F5 
$F262 
$DA46 
$D93E 
$D912 


(continued) 
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Table 4-2. Applesoft keyword tokens (continued). 


Address of 

Token Keyword Subroutine 

$AD IF $D9C9 

$AE RESTORE $D849 

$AF & $03F5 

$BO GOSUB $D921 

$B1 RETURN $D96B 

$B2 REM $D9DC 

$B3 STOP $D86E 

$B4 ON $DIEC 

$B5 WAIT $E784 

$B6 LOAD $03F5 

$B7 SAVE $03F5 

$B8 DEF $E313 

$B9 POKE $E77B 

$BA PRINT $DAD5 

$BB CONT $D896 

$BC LIST $D6A5 

$BD CLEAR $D66A 

$BE GET $DBAO 

$BF NEW $D649 

$CO TAB( 

$C1 TO 

$C2 FN 

$C3 SPC( 

$C4 THEN 

$C5 AT 

$C6 NOT 

$C7 STEP 

$C8 + 

$C9 - 

$CA * 

$CB / 

$CC ” 

$CD AND 

$CE OR 

$CF > 

$DO = 

$D1 < 

$D2 SGN $EB9O 

$D3 INT $EC23 

$D4 ABS $EBAF 

$D5 USR $0Q00A 

$D6 FRE $E2DE 

$D7 SCRN( $D412 

$D8 PDL $DFCD 

$D9 POS $E2FF 


(continued) 
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Table 4-2. Applesoft keyword tokens (continued). 


Address of 
Token Keyword Subroutine 
$DA SOR $EE8D 
$DB RND $EFAE 
$DC LOG $E941 
$DD EXP $EFOI 
$DE COS $EFEA 
$DF SIN SEFF1 
SEO TAN $FO3A 
$E1 ATN $FO9E 
$E2 PEEK $E764 
$E3 LEN $E6D6 
$E4 STR$ $E3C5 
$E5 VAL $E707 
$E6 ASC $E6E5 
$E7 CHR$ $E646 
$E8 LEFT$ $E65A 
$E9 RIGHT$ $E686 
$EA MID$ $E691 


1D @8 64 08 5849 DO 34 CA E1 28 31 293A 


address line P I token 4 token token ( 1 ) 
of next number for for for 
line = * ATN 


BA 2258 49 28 3D 29 22 3B 50849 3A 88 00 


token P it = Pp I token end of 
for for line 
PRINT END marker 


Notice that the five keywords in this line, =, *, ATN, PRINT, and END, 
have been replaced by their tokens, $D0, $CA, $E1, $BA, and $80, respectively. 
Also notice that each character that is not part of a keyword is not tokenized 
and is represented by its ASCII code. 


Storage of Applesoft Variables 


Now that we have seen how an Applesoft program is stored in memory, 
let's take a more detailed look at how and where the program’s variables are 
stored during program execution. Not only is the knowledge of the data 
structures used to store variables fundamentally interesting, it will undoubt- 
edly be invaluable to those who wish to manipulate Applesoft variables from 
within 65C@2 assembly-language subroutines that are called from Applesoft. 
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Applesoft supports four fundamental variable types. There are three numeric 
types (integer, real, and function) and one alphanumeric type (string). Integer 
numbers are made up of all positive and negative whole numbers and zero, 
that is, all numbers that have no fractional parts (Applesoft handles all those 
integers between —32767 and 32767). Real numbers, also called floating-point 
numbers, are made up of all numbers, including those that do have fractional 
parts. Strings are simply sequences of characters; the characters are encoded 
using the ASCII scheme (see Chapter 6). Functions are special variables that 
are defined by the Applesoft DEF FN command and that are evaluated using 
a user-specified mathematical expression. For example, if a function is defined 
as follows: 


DEF FN MDCX)=X-256*INTCX/256) 


then whenever the value of MD(aexpr) is requested (where “‘aexpr’’ represents 
an arithmetic expression) it is evaluated by substituting the value of ““aexpr”’ 
wherever ‘‘X”’ appears in the “X—256*INT(X/256)” formula and then calcu- 
lating the result. 


The first character of an Applesoft variable name must begin with a letter 
fromA ...Z(youcan enter it in upper- or lowercase on the //c—Applesoft will 
automatically convert it to uppercase); subsequent characters can be either 
letters or a digit from @ ...9. The variable name can be up to 239 characters 
in length, but only the first two characters are significant (the rest are simply 
ignored). This means that Applesoft considers the variables LESS and LESSEN, 
for example, to be equivalent. 


A variable name cannot be used that contains the names for any of the 
keywords shown in Table 4-2. For example, the variable name ‘‘LETTER” is 
illegal because it contains the LET keyword. 


If an integer or string variable is being defined, a special variable identifier 
symbol must be added to its name so that Applesoft can properly interpret it 
and store its value. The variable identifier symbol for integer variables is “%’’ 
and for string variables it is “‘$’’. No special identifier symbol is needed to 
identify real or function variables. Table 4-3 sets out the variable identifier 
symbols used by Applesoft. 


When a variable is defined in a program, Applesoft stores its name and 
value at the end of one of two memory spaces located after the end of the 
program. One space is reserved for simple variables and functions and is 
pointed to by VARTAB ($69). The other space is reserved for array variables 
and is pointed to by ARYTAB ($6B). In the following sections, we will take a 
look at how variables are represented in these two variable spaces. 


Storage of Simple Variables 


Whenever Applesoft has to make use of a certain variable, it has to locate 
it within its variable space. It does this by searching the variable space 
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Table 4-3. Applesoft variable identifier symbols. 


Variable 
Identifier 
Symbol Variable Type Example 
[none] real AB 
% integer AB% 
[none] function FN ABC ) 


$ string AB$ 


beginning with the first entry and continuing until it finds a match. Thus, the 
farther into the space a variable is located, the longer it will take Applesoft 
to find it. Since Applesoft stores variables in its variable space in the order in 
which they are encountered when the program is executed, you can improve 
program execution speed by ensuring that more frequently used variables 
are defined before less frequently used ones. This is most easily done by 
defining all the frequently-used variables in the desired order as soon as the 
program starts executing. For example, if your program uses four variables, 
say I,J, K, and L§, but you would like K to be accessed as quickly as possible, 
then you should execute a line such as 


16 K=9:7[=@:J=9:Lg="e"' 
before any other line that defines or uses any variables. 


Each entry in the simple variable space is exactly seven bytes long and 
consists of two parts: the name header, which is used to store the variable’s 
name and type, and the data field, which contains the encoded value of the 
variable or a pointer to its location. The storage format used for each type of 
variable is summarized in Figure 4-2. 


The Name Header 


The name header contains all the information related to the variable’s type 
and name so that it can be quickly located and accessed whenever it is referred 
to during execution of the Applesoft program. The name header for a simple 
variable is always exactly two bytes long. Stored in these two bytes are the 
7-bit ASCII codes for the the first two characters of the variable’s name; if 
there is only one character used in the name, then the second character is 
assumed to be the ASCII null character, $00. The high-order bits of each of 
the two bytes are used to indicate the type of simple variable being referred 
to. For example, for a string variable, these bits will be OFF (0) and ON (1), 
respectively. For real and integer variables, they will be OFF-OFF and ON- 
ON, respectively. Lastly, the bits will be ON-OFF if the name refers to a 
function defined by the DEF FN command. 
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(a) Real variables. (b) Integer variables. 


(c) String variables. (d) Function variables. 


First name byte First name byte 
second name byte Second name byte 
, Pointer to 
Length of string function (low) 
Pointer to Pointer to 
function (high) 


string (low) 
Location of argument 
data (low) 


high bit ON 


high bit OFF 


high bit OFF high bit ON 


high bit OFF high bit ON 


high bit ON high bit OFF 


Pointer to 
String (high) 


Location of argument 
data (high) 


First character following 
“=” in FN definition 


[Not used] 


[Not used] 


Figure 4-2. Storage formats for Applesoft simple variables. 


The Data Field 


The encoded data that relates to the value of the simple variable are stored 
in five bytes just after the end of the two name header bytes. Despite the fact 
that five bytes are always reserved for data storage, however, only real vari- 
ables and functions make use of them all. The number of bytes required for 
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the data for each type of variable is as shown in Table 4-4, as are the restric- 


tions on the values for each type of Applesoft variable. 


Table 4-4. Storage requirements and limitations for Applesoft 
variables. 


Number of 
Variable Data Bytes 
Type Required Restrictions on Variable Value 
Integer 2 — 32767 ... +32767 
Real 5 2.9E-39 ...1.7E+ 38 (pos. or 
neg.) 

String 3 Length of string is@...255 
Functions 5 One argument only 


Let’s take a look at the storage formats used for each type of variable. 


Integer. The data for integer variables is stored in a signed ‘‘two’s com- 
plement’ format and occupies two bytes (most-significant byte followed by 
least-significant byte). See the section below entitled ‘‘Representation of Inte- 
ger Numbers’ for a detailed description of the two’s complement storage 
format. The high bit of the most-significant byte can be read to determine the 
sign of the number. If this bit is 1, then the number is negative; if it is @, then 
the number is positive. The last three bytes of the data field are not used. 


Real. The data for real numbers is stored in all five bytes. The first byte is 
related to the exponent of the number and the next four bytes represent its 
signed mantissa, most-significant byte first. The sign bit is the high bit of the 
second byte of the five. See the section below entitled ‘Representation of Real 
Numbers’ for a detailed description of the method Applesoft uses to store 
real numbers. 


String. The data for string variables is really made up of two parts. The 
first part is stored in the variable table itself and is a three-byte ‘‘descriptor’’ 
that represents the length of the string (first byte) followed by a two-byte 
pointer (low-order byte first) to a sequence of ASCII-encoded characters that 
defines the string itself. The second part is, in fact, made up of those characters 
that define the contents of the string. 


The contents of strings are normally stored in the high end of memory ina 
string space beginning at a location pointed to by MEMSIZ ($73) and ending 
lower in memory just before the location pointed to by FRETOP ($6F). When- 
ever a new string is entered from the keyboard or a diskette file, or an old one 
is manipulated using any of Applesoft’s string-handling commands, it is placed 
in memory just before the address to which FRETOP points in such a way 
that the first character in the string is located lowest in memory and the last 
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character is located at the location pointed to by FRETOP. After this is done, 
FRETOP is adjusted downward so that it points to the byte immediately 
before the beginning of the string just stored. 


When a string variable is redefined using Applesoft’s string-handling com- 
mands, its new definition is placed in the string space in the upper part of 
memory as if it were a newly defined variable; however, its.former characters 
are not immediately removed from the string space even though it is no longer 
used. This means that if strings are continuously being redefined, a lot of 
unused information will accumulate in the string space and eventually the 
address stored in FRETOP will come very close to the address stored in the 
end-of-variable pointer, STREND ($6D). 


When this happens, a procedure is initiated that maximizes the available 
free space by removing the unused string characters, packing the currently 
active string characters up to the high end of memory, and resetting FRETOP. 
This procedure is called ‘‘garbage collection” or, more euphemistically, ‘““house- 
cleaning’. Applesoft’s own garbage collection routine can last anywhere from 
a few seconds to a few minutes, depending on the number of string variables 
that have been defined in the program. However, when an Applesoft program 
is running in a ProDOS environment, a garbage collection routine within the 
BASIC.SYSTEM program that interfaces Applesoft to ProDOS (see Chapter 
5) is used instead and it handles the collection virtually instantaneously. 


Note, however, that if a string is explicitly defined within the program 
itself, for example, in a program line that looks like this: 


180 A$="THIS IS A TEST" 


then the string pointer in the variable’s data field will point to the definition 
inside the program itself and not to a location within the usual string space. 
Such a string will be moved into the string space only if it is operated on by 
an Applesoft string-handling command. 


Functions. The data for functions is stored in five bytes. The first two 
bytes act as a pointer to the body of the function’s definition within the 
program (that is, the part after the “=” sign in the DEF FN definition). The 
next two bytes contain the address of the data field for the variable repre- 
senting the function’s argument. The last byte contains the first byte in the 
function definition. 


End of Simple Variables 


ARYTAB ($6B) points to the Applesoft array variable space located imme- 
diately after the end of the simple variable space. Whenever a new simple 
variable is defined, the whole of the array variable space is moved up in 
memory by seven bytes to make room for the new simple variable definition 
and the end-of-variables pointer, STREND ($6D), is adjusted accordingly. 
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The name header and data bytes for the variable are then stored beginning 
at ARYTAB. ARYTAB is then increased by seven so that it equals the new 
starting position of the array space. 

The simple and array variable spaces are also moved upward and down- 
ward in memory as program lines are added to or deleted from the program. 


Storage of Array Variables 


Each entry in the array variable space is made up of a name header, special 
dimensioning bytes that indicate the size of the array and how it is indexed, 
and a data feld. The storage format used for each type of array variable is 
summarized in Figure 4-3. Note that arrays are permitted for each Applesoft 
variable type except functions. 


The Name Header 


Just as for simple variables, entries for array variables begin with a name 
header. The name headers for array variables are identical to those for the 
corresponding simple variables discussed in the previous section (for exam- 
ple, the header for an array dimensioned as AB(5,6) is the same as for AB). 


Dimensioning Bytes 


When array variables are stored, a series of bytes that describe the number 
of dimensions of the array and their sizes are placed in memory just after the 
header. 


First, two bytes are used to store a number that is equal to the number of 
bytes that the array occupies in the array variable space. This number is 
simply the offset from the name header of this array to the next array and is 
stored here so that the address of the next array variable in the array space 
can be quickly and easily calculated when Applesoft is searching for an array. 
The number is stored with the low-order byte first. 


The next byte is equal to the number of array indexes (or “dimensions’’) 
and can be from 1 to 255. For example, an array dimensioned as AB(3,5,2) 
would have a value of 3 stored in this byte. 


Pairs of bytes follow this last byte that indicate the size of the indexes of 
the array, with the number of elements in the last index being stored in the 
first pair and the number of elements in the first index being stored in the 
last pair. The high-order byte is stored first in each pair. The numbers stored 
here will be one higher than the number used when the array was first 
dimensioned (using the DIM statement) since it starts counting the elements 
from 1 rather than Q. 
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Let’s look at an example. The name header bytes and dimensioning bytes 
for an array dimensioned as AB(3,5,2) would be as follows: 


41 42 73 G1 93 68 93 99 06 68 84 
name offset to # of size of size of size of 
(AB) next array indexes 3rd index 2nd index Ist index 


Header used by all three array variable types: 


First name byte 
Second name byte 


Offset to next 
array variable 
(low byte first) 


Number of dimensions 


Size of last 
dimension 
(high byte first) 


Size of first 
dimension 
(high byte first) 


(a) Real variables. (b) Integer variables. (c) String variables. 


Exponent + 128 Value (high) Length of string 


first 


, element Pointer to first 
Mantissa (high) Value (low) string (low) element 
first Pointer to 
element string (high) 
Mantissa (low) Value (high) last 
element 
Value (low) Length of string 
Pointer to last 
Exponent + 128 string (low) element 
Pointer to 


Mantissa (high) 
Mantissa (low) 


Figure 4-3. Storage formats for Applesoft array variables. 


String (high) 


last 
element 


NOTE: Array elements are stored in such a way that 
the right-most dimensioning index increases slowest (see text). 
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The Data Field 


After the dimensioning bytes come the actual data bytes for each array 
element. They are stored in exactly the same formats used by the correspond- 
ing simple variables except that, in the case of integer and string arrays, the 
data bytes are packed. This means that the unused bytes that are stored in 
the simple variable data space for these two types of variables are not stored. 


The array elements are stored in memory in such a way that the rightmost 
dimensioning index ascends most slowly. Thus, if an array is dimensioned as 
A(1,1), then A(@,0) is stored first, followed by A(1,0), A(@,1), and then A(1,1). 


End of Array Variables 


STREND ($6D) points to one byte past the end of the array variable space. 
It also points to the beginning of Applesoft free space. When a new array 
variable is defined, its header and data are stored beginning at this location 
and then the value STREND is increased by the size of the entry for the array. 


Representation of Integer Numbers 


Applesoft stores the data for its integer variables in a special two-byte 
format called “two’s complement.” As we will see, the advantage of using 
this format is that it allows both negative and positive numbers to be repre- 
sented in a way that greatly simplifies the execution of the two basic signed 
arithmetic operations, addition and subtraction. 


The most-significant byte of the pair of data bytes reserved for an integer 
is stored first (note that this is just the opposite of how two-byte quantities 
are usually stored). The high-order bit of this byte is used to indicate the sign 
of the number. If it is 1, then the number is negative; if it is @, then it is 
positive. The remaining 7 bits of this byte, and the 8 bits of the least-significant 
byte, are used to represent the magnitude of the integer. For a positive integer, 
the 15-bit magnitude is simply represented by the standard unsigned binary 
pattern for the integer. For example, 


00009001 960000011 
is used to represent + 259 ($0103). 


The 15 bits used to represent a negative integer are determined somewhat 
differently. To determine what they are, you must first take the binary pattern 
for the absolute value of the integer (that is, its positive counterpart), com- 
plement it by changing all its 1 bits to @ and vice versa, and then add one to 
the result. The most-significant bit will then be 1, indicating that the number 
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is negative. For example, the representation for the integer —11 would be 
calculated as follows: 


0000000 00001011 (+11) 
1111111 11110100 (complement) 
+ 1 (add 1) 
1111111 11110101 (—11 in two’s complement) 


Using the two-byte two's complement format, it is possible to define integers 
that range from —32768 (10000000 00000000) to + 32767 (91111111 11111111). 
Note, however, that even though the number —32768 can be represented in 
the two-byte two's complement format, Applesoft does not allow its integer 
variables to take on this value. The lowest value that is allowed is —32767. 


Applesoft stores its integers in this apparently strange format to simplify 
the way in which binary arithmetic can be performed. By using the two’s 
complement format, positive and negative numbers can be easily added and 
subtracted without having to perform the complicated adjustments needed 
to account for the different signs of the numbers if any other representation 
is used. (Another representation may be the conventional “sign plus magni- 
tude” (S+M), where a positive integer and its negative counterpart are iden- 
tical except for the value of the sign bit.) When using the two’s complement 
representation, it is only necessary to add the 16-bit representations of the 
two integers (be they positive or negative) as if they were just two standard 
unsigned binary numbers. The result, and its sign, will then automatically 
be correct if the result is viewed as another two’s complement integer (which 
it is). 

Let’s take a look at an example to see what we mean by this. Consider the 
problem of adding the integer +8 to the integer —5. If these numbers were 
stored in their normal binary representations with the sign bit being the 
most-significant bit, then the calculation to be performed would be 


00000000 00001000 (+8) 
+ 10000000 00000101 (—5 inS+M binary) 


10000000 00001101 (—13 inS+M binary) 


This result is, of course, wrong. Thus, if this representation is used, special 
programs must be written to avoid these erroneous results. On the other hand, 
if the integers are represented in the two's complement format, then the 
calculation becomes 


00000000 00001000 (+8) 
+ 11111111 11111011 (—5 in two's complement) 
00000000 00000011 (+3) 


This result is, of course, correct. If you experiment with other integers, you 
will see that the signed result is always correct (unless the result is out of the 
allowable range). 
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Representation of Real Numbers 


As we have seen, Applesoft real numbers are stored in the simple variable 
space and array variable space in a binary floating-point format. This special 
format will be described in detail now. 


Knowledge of this format will be of use mainly to those who write 65C02 
assembly-language programs that access Applesoft numeric variables. How- 
ever, even if you never intend to write such a program, the following infor- 
mation should prove to be interesting. | 


Number Theory 


Even though numbers are commonly entered into a computer in a ‘‘deci- 
mal” or “‘base 10” format, they are generally stored internally in some sort 
of compressed binary format to reduce data storage space and to make it easy 
for programs to manipulate them. 


Decimal integer numbers can be stored in a binary form without loss of 
accuracy due to rounding or truncation (provided that the integers are within 
the numeric range supported by the computer) because they do not contain 
fractional parts. On the other hand, floating-point numbers (that is, real 
numbers), which do have fractional parts, can only be “approximated” by a 
binary representation unless the decimal number is exactly equal to a sum 
of powers of two. Because approximations have to be made in most cases, 
you will sometimes find that if you multiply a number by its reciprocal in 
Applesoft that the number calculated is not equal to one! 


Floating-point real numbers are often expressed in ‘‘scientific notation” 
that looks like this: 


134.56 x 10%6 


The first part of this representation is called the mantissa and the second 
part is called the exponent (the exponent is actually the number to which the 
number base being used has been raised). An understanding of scientific 
notation is important because it is a binary mantissa and exponent that are 
stored by Applesoft when real numbers are saved in its variable spaces. 


Binary Floating-Point Format 


Real numbers are stored in the variable spaces of Applesoft in a “binary 
floating-point” format. As indicated in Figure 4-4, this is a five-byte format in 
which one byte is reserved for exponent information and four bytes for man- 
tissa information. The mantissa contains the binary representation of the 
fractional part of the number. 


The lowest-addressed byte in the fivesome is the exponent byte. The value 
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stored here is actually not the exponent itself but rather the value of the 
exponent plus 128. Because this method is used to store the exponent, the 
exponent is said to be “biased” by 128. 


Before a number is stored in the binary floating-point format, it is “‘nor- 
malized.’ Normalization is the process whereby the binary point of the binary 
number (as opposed to a decimal point for a decimal number) is adjusted so 
that there is a ‘‘1”’ to its immediate right and no “1”’ ’s to the left of it. Thus, 
after normalization, the mantissa of the number will be between @.1 and 
@.11111111... (Gin binary). For each movement of the binary point to the left, 
the exponent is increased by one; for each movement to the right, the exponent 
is reduced by one. For example, consider the binary number “1101.11”. To 
normalize this number, the binary point must be moved four places to the 
left; thus, the initial exponent (@) must be increased by four. 


In the binary floating-point representation, the high-order bit of the second 
byte represents the sign of the number. If this bit is 1, then the number is 
negative; if it is 0, then the number is positive. 


The remaining 7 bits of the second byte and the remaining three bytes are 
used to represent the mantissa of the number, most-significant byte first. 
Within a particular byte, the 7th bit is the most significant and the Oth bit 
the least significant. As has been explained, the mantissa has been normalized 
so that there is a “‘1’’ to the immediate right of the decimal point; this “1” is 
implicit and is not stored. Thus, a floating-point number has 32-bit precision 
(about nine decimal digits) even though only 31 bits are actually used to hold 
the mantissa. 


Any number whose exponent byte is equal to zero is considered to be zero 
by the Applesoft interpreter even though its mantissa bytes may be nonzero. 


The decimal range of numbers that is allowed using the five-byte binary 
floating-point format is as follows: 


+/- 2.9387355E-39 to +/- 1.70141183E+38 


To calculate a decimal number from its binary format, multiply the value 
of each mantissa bit by its corresponding binary weight, add the implied 0.5 
(which is the decimal equivalent of binary 0.1), and then multiply the total 
by 2 raised to the value of the exponent byte minus 128. The binary weight 
of a particular mantissa bit is given by (1/2)*(32-BN), where BN is the bit 
number. The bit numbers range from the most-significant bit 30 (bit 6 of byte 
2) to the least-significant bit @ (bit 0 of byte 5). 


For example, consider the decimal number '8.67’. It is stored by Applesoft 
as the following five bytes: 


BYTE1 BYTE2 BYTE3 BYTE4 BYTES 
$84 $O0A $B8 $51 $EB 


and the corresponding binary number is 


__. 4/ Applesoft BASIC [| 89 


+.10081010 10111000 01010001 11161011 * 2%84- $88 
byte2 byte3 byte4 byte5 bytel 


implicit 


To convert this binary number to its corresponding decimal number, you 
must add the implicit 0.5 to the sum of each binary digit multiplied by its 
binary weight. The resultant calculation is as follows: 


8.5+€1/29*%5+01/29%7+01/29%°9+01/29%114+01/29%12 
+€1/2)9%13+01/29%184+01/29%20+01/2)9%24+01/2) 
*25+¢01/29*%26+01/2)9%27+01/2)9%29+01/2)9%31 
+01/2)%32 


If you calculate this quantity, you will get 0.541875. It then must be mul- 
tiplied by the exponential part (which is 2“4 or 16) in order to yield the final 
result: 8.67. 


Note that the high bit of BYTE2 in the above example is zero indicating 
that the number is positive. 


If you wish to look at the bytes that Applesoft uses to store other numbers, 
use the program found in Table 4-5. When you RUN this program, you will 
be asked to enter a number to be analyzed (X). The program locates the data 
bytes used to store this number by recognizing the fact that since X is the 
first simple variable defined in the program, its five data bytes must be stored 
two bytes from the beginning of the simple variable space (remember that 
the first two bytes are reserved for the name header). The address of the 
beginning of this space is simply PEEK(105) + 256* PEEK(106) since the pointer 
to the beginning of the simple variable space is located at $69 and $6A. 


BYTE #1 BYTE #2 BYTE #3 BYTE #4 BYTE #5 


Exponent Mantissa Mantissa 
+ 128 (highest) (lowest) 
sign 
bit 


Figure 4-4. Applesoft binary floating-point format. 


How an Applesoft Program Runs 


Right after you enter the RUN command to begin execution of an Applesoft 
program, at least two important things happen. First, all the pointers to the 
variable spaces are initialized, effectively destroying any variables that may 
have been active when the program last stopped running. Then, just before 
the program starts to be executed, a special pointer, called TXTPTR ($B8/ 
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Table 4-5. REAL._NUMBERS—a program to display the bytes that 
are used to represent an Applesoft real variable. 


6 REM "REAL.NUMBERS” 

1080 TEXT : HOME : PRINT "DECIMA 
L ---> BINARY FLOATING-POINT 

110 VTAB S 

1280 INPUT "ENTER NUMBER TO BE C 
ONVERTED: ';X 

130 DIM HX$C15): FOR I = 6 TO 1 
S: READ HX$CI): NEXT 

148 XD = PEEK (105) + 256 * PEEK 
C106) + 2: REM LOCATION OF 
DATA FOR X 

150 PRINT : PRINT “THE FLOATING 
-POINT REPRESENTATION IS:": PRINT 


168 FOR I = XD TO XD + 4 
176 D = PEEK (1):D1 = D 
18@ PRINT “BYTE #":I - XD + 13" 


199 FOR J = 7T0O @ STEP - 1 

209 T = INT CD / €C2@ Jd): PRINT 
T; 

2196 Dz D- iT * €2 J) 

2206 NEXT J: PRINT ™ C$"sSHX$C INT 
CD1 / 16))3;HX$CD1 - 16 * INT 
CD1 / 16))3;") "s 

230 READ DS$: PRINT DS$ 

246 NEXT I: PRINT 

250 PRINT “BIT 7 OF BYTE #2 IS 
THE SIGN BIT": PRINT "CQ --»> 
POSITIVE, 1 --> NEGATIVE)" 

C69 DATA 9,1,2,3,4,5,6,7,8,9,A, 
B,C,D,E,F 

27@ DATA EXPONENT + 128,MANTISS 
A HIGH,.,.,MANTISSA LOW 


$B9), is initialized so that it contains the address of the beginning of the 
program. This address is normally $801. 


TXTPTR is an important pointer as far as the interpreter is concerned 
because it always contains the address of the location within the program 
that the interpreter is acting on. Whenever the interpreter wants to examine 
the next byte of the tokenized program, it simply increments this pointer and 
then reads the new byte to which it points. 
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The CHARGET Subroutine 


Since TXTPTR must be incremented by many different subroutines in the 
interpreter, one special subroutine is used to take care of it. This subroutine 
is called CHARGET (for CHARacter GET) and is located in page zero from 
location $B1 to location $C8. A source listing of CHARGET appears in Table 
4-6. Another subroutine, called CHARGOT, is contained within CHARGET; 
this subroutine reads the current byte being pointed to without incrementing 
TXTPTR. An image of the CHARGET subroutine is loaded into its page zero 
locations from the Applesoft ROM area by the Applesoft interpreter when 
Applesoft is first initialized. It must be placed in a RAM area because, as we 
will see, it contains self-modifying code. 


TXTPTR is actually located within this subroutine at location $B8/$B9 and 
it forms the operand of an LDA instruction that retrieves the value of the byte 
pointed to by TXTPTR. 


When CHARGE T is called, TXTPTR is incremented, the 65C@2 accumulator 
is loaded with the byte located at the new address it points to, certain pro- 
cessor flags are set, and then the routine ends. Exactly how the flags are set 
depends on the value of the byte loaded into the accumulator. If it is an end- 
of-line marker (@) or end-of-statement byte ($3A), then the zero flag (Z) is set; 
otherwise, it is cleared. In addition, if the byte is a digit (that is, its ASCII 
code is between $30 and $39), then the carry flag (C) will be clear; otherwise, 
it will be set. The reason for testing for these conditions in the CHARGET 
subroutine is that many of Applesoft’s internal subroutines are constantly 
checking for end-of-line conditions or for the presence or absence of numbers 
and this is an efficient way of providing that information. If it wasn't done 
this way, then wasteful duplication of code would be required because every 
subroutine that needed the information would have to perform its own sep- 
arate testing procedures. 


Let’s get back to our program, which was just starting to run with TXTPTR 
set to $801 when we last left it. Since the first four bytes of the program 
($801 .. . $803) are simply the line number and the address of the next line, 
they are skipped over by increasing TXTPTR by four so that the next time 
CHARGE T is called the first byte in the token field of the program line will 
be read. 


The next step, of course, is to call CHARGET and get that first byte and 
analyze it. This is where Applesoft really starts its interpretation chores. If 
the byte happens to be an end-of-line marker (0), then TXTPTR is bumped by 
four positions so that it points to the byte just before the token field of the 
next line. If it’s a colon separator ($3A), then CHARGET is called again to 
load the next byte (which will be the first byte in the token field of the next 
statement on that line). 


If the byte is a keyword token (that is, it is greater than or equal to $80), 
then, assuming it is not out of context, the appropriate subroutine in the 


92 [|__| _ Inside the Apple //c 


Sla LIXJ Lg 09 -8008 
ueato aq T{Ttm Auseo *yrthrp 41! ga$* aS G2 6d 63 '9000 
03S Gl BE -S000 
GES# O4S 8 | GE 64 *€0090 
J3dS Li BE +2000 
a3iAq jxau 336 os ‘sayt LAOAVYVHO O35 Ot 33 64 -0008 
44ueTG B Sty} SJ]: O2$# dWd St 92 60 +3800 
ota =¢ fT YOUBUG: LIX3 SO bl 06 04 -J88G 
wis, OF} JT Buedwoo pue ¢ VES# dW E14 VE 60 *VEOe 
01 payutod a3yAq ayy 329: d4455¢ VAT LOOAVHO cl 43 33 AV *2E06 
b+ALldLXL INI Lt 6G 95 -Sd900 
uot}ytsod auo Aq : LO9SAVHO J3NE 61 c8 894 -€dGs@ 
vayutod 4xa} ayy dwng: SidLXL ONI LIDAVHO 6 8H 935 - 18900 
8 
Ld$ 9a0 Z 
9 
CL+LOOANVHOD St STYL *3LON)D: 84$ NJ SLldLXL S 
v 
HEHRHHEHHEE EH ¢ 
* LAIOSAVHO * A 
HHHEKREHREE HS | 


‘meis0i1d yjJosajddy ue aszed 0} pasn st Jey} aUTNOAQGNS 394]— LADUVHO °9-h FAGeL 


4/Applesoft BASIC [|] 93 


interpreter that handles that command or function to which it refers will be 
called. That subroutine will, among other things, evaluate numerical or string 
expressions and perform syntax checking; it will do this by making extensive 
use of CHARGET to analyze the bytes “surrounding” the keyword. When the 
keyword has been dealt with, CHARGET will point to the next byte to be 
interpreted. 


If the byte is not a keyword token or an end-of-line or end-of-statement 
marker, then, depending on the context, it may be considered to be a variable 
name, a piece of data, or maybe nothing at all (in which case you will see the 
dreaded PSYNTAX ERROR). As long as no syntax errors are detected, TXTPTR 
will continue incrementing and interpreting new bytes until such time as the 
token for END or STOP is encountered or until the last line in the program, 
denoted by a pair of zero bytes where the next line pointer would normally 
be found, has been executed. 


Changing Program Flow 


Because Applesoft always relies on the value of TXTPTR to determine what 
part of the program to execute next, you can easily cause Applesoft to skip 
certain parts of the program and to continue executing elsewhere merely by 
adjusting TXTPTR. In fact, this is exactly how the Applesoft GOTO and 
GOSUB commands work. When the interpreter encounters either of these 
commands, it performs a number of tasks, the most important of which are 
to determine the target line number, to find that line number in memory, and 
then to store the address of the line’s token field in TXTPTR. Then, when 
Applesoft continues interpreting the program by calling CHARGET, the com- 
mands there will begin to be executed. 


Finding Line Numbers 


We have just seen how TXTPTR is adjusted when either a GOTO or GOSUB 
command is executed. What we did not explain is how the interpreter deter- 
mines where the line is located to which control is to be passed by either of 
these commands. 


There are two different methods Applesoft uses, depending on whether the 
high-order byte of the destination line number is greater than the high-order 
byte of the current line number. If it is, then the interpreter starts looking for 
a line with the proper number beginning with the next line in memory. If it 
is not, then the interpreter begins with the first line of the program. The 
interpreter can quickly skip over lines whose numbers don’t match by exam- 
ining the link field address (the first two bytes of the tokenized line) to deter- 
mine the address of the next line of the program. 


What this means is that GOTO and GOSUB commands that transfer control 
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to line numbers just before the current line will execute more slowly than 
those that transfer control to lines nearer the start of the program or to lines 
just after the current line. 


In should be obvious, then, that to increase program execution speed, 
“backward” GOTO and GOSUB statements should transfer control to lines 
that are as close to the beginning of the program as possible. By placing 
commonly used subroutines near the beginning of a program in decreasing 
order of activity, program speed can be noticeably increased. 


Linking Applesoft to Assembly-Language 
Programs 


The execution speed of an Applesoft program can be improved dramatically 
by linking it to assembly-language subroutines. This is because the code 
generated by the assembly process is directly executable by the microproces- 
sor and does not have to be interpreted first. Such subroutines can be accessed 
from Applesoft by using one of three Applesoft commands: CALL, USR, and 
& (ampersand). These three commands are summarized in Table 4-7. 


Assembly-language subroutines often need to make use of zero page loca- 
tions to take advantage of some of the 65C@2’s more powerful addressing 
modes. As we have seen, however, several locations in zero page are reserved 
for use by Applesoft pointers. Others are used by Applesoft, the system mon- 
itor, or ProDOS for other purposes. Table 2-5 at the end of Chapter 2 contains 
a complete list of those zero page locations that are not used and that are 
available for use by an assembly-language program. 


Table 4-7. Applesoft to assembly-language commands. 


Command Description 
CALL aexpr Transfers control to the memory location specified by 
“aexpr’ 


X = USR(aexpr) Evaluates “aexpr’’ and places the result in the floating 
point accumulator (see text) and then transfers control to 
$000A. On return, the value of the function is set equal to 
the value in the FAC. 


& Transfers control to $3F5. 


Note: ‘‘aexpr’’ represents an arithmetic expression. 
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The CALL command 


The CALL command is the one that is usually used to link Applesoft pro- 
grams with assembly-language subroutines. If such a subroutine begins at a 
memory location represented by “‘aexpr,” then you would use the command 


CALL aexpr 


to invoke the subroutine. The value of ‘‘aexpr”’ that you use must be a literal 
decimal number (not hexadecimal) or, alternatively, a mathematical expres- 
sion that evaluates to an integer number. 


For example, to execute a subroutine from Applesoft that begins at location 
$300 (768 decimal), you would use the command 


CALL 768 


When the subroutine finishes executing, you will normally return to Apple- 
soft and the next statement in the Applesoft program will be executed. 


You can try using the CALL command without even writing any assembly- 
language subroutines simply by accessing subroutines that are already con- 
tained in the system monitor ROM. For example, to clear the screen you 
would use the command CALL 64600 since $FC58 is the address of the screen 
clear command. As explained in Chapter 3, there are many other subroutines 
in the monitor, some of which require that data be provided to them first or 
that registers be set up in certain ways. 


If the subroutine that you are calling requires that data be provided to it 
before it can perform its duties, you would normally precede your CALL with 
several POKE commands that would place the appropriate information at 
the locations expected by the subroutine. Similarly, you will usually have to 
use the PEEK command to examine any numerical results that the program 
may store in memory. 


It is possible, however, using more advanced techniques, to pass the values 
of named variables to and from your called subroutines. These techniques 
will be described below in the section entitled ‘Using Applesoft’s Built-in 
Subroutines.’ 


The & Command 


The & (ampersand) command is similar to the CALL command and is used 
for similar purposes. Whenever the Applesoft interpreter comes across the & 
command, it immediately causes the system to transfer control to location 
$3F5, thus causing the subroutine that is located there to be executed. In the 
usual case, a 65CQ@2 JMP (jump) instruction is stored at this location that 
passes control to some other location where the main body of the subroutine 
begins. 
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If you want to use the & command to access assembly-language subroutines, 
you must first set up the jump at location $3F5 (1013) so that it points to the 
desired subroutine. This can be done by using the following three POKE 
commands: 


POKE 1813,76 REM 76 C$4C) is the 65C02 JMP opcode 
POKE 1014,YY REM YY _ is the low address of the sub. 
POKE 1015,XxX REM XX isthe high address of the sub. 


To calculate the high and low halves of the address of the subroutine, you 
can use the following formulas: 


XX INTCADDRESS/256) 
YY ADDRESS - 256*XX 


After you install the subroutine at the proper location, you can then execute 
the & command to access it. 


As with the CALL statement, no built-in provisions have been made for the 
passing of variables to and from & subroutines. However, the program that 
is called can be written to do this for itself. See the section below entitled 
“Using Applesoft’s Built-in Subroutines.” 


The USR Function 


The USR function can also be used to link Applesoft to assembly-language 
subroutines. The syntax of the USR function is as follows: 


Y = USRCaexpr) 


where “‘aexpr’’ represents a mathematical expression that is called the argu- 
ment of the function. When the USR function is encountered by the inter- 
preter, the formula is evaluated, the result of the evaluation is placed in an 
internal floating-point accumulator (FAC) in zero page and a jump to location 
$000A is performed. By setting up a 65C@2 JMP instruction at $000A, you can 
transfer control to the beginning of an assembly-language program that has 
been loaded anywhere in memory. 


After the program has finished executing, control will return to Applesoft 
and the Y variable in the above equation will be set equal to the current value 
of the FAC. This is why USR is called the ‘“‘user-defined function.” 


Let’s take a look at a specific application involving the USR command. In 
particular, let’s calculate the sine of the argument by using Applesoft’s inter- 
nal sine evaluation subroutine located at $EFF1. As we will see later in this 
chapter, this subroutine calculates the sine of the number in the FAC and 
returns the result there. The subroutine required to perform the conversion 
is simple: JMP $EFF1. You can install it at location $300 by entering CALL — 
151 to enter the system monitor, and then entering the command 
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399:4C F1 EF 


To link this subroutine to the USR command, a JMP $300 instruction must 
be placed at the USR locations from $A to $C. This can be done by entering 
the following monitor command: 


A:4C 80 83 


where 4C is the JMP opcode and 00 03 represents the address of the subroutine 
(low-order byte first). Note that you could have also entered all this infor- 
mation using Applesoft POKE statements. 


To try out the USR routine, enter and RUN the following short program 
after entering the data at $300 and $@A to $0C as discussed above: 


100 X = 3 
208 PRINT USR CX) 
308 PRINT SIN CX) 


As you will see after the program has executed, USR is indeed calculating 
the sine of X. 


USR is not a popular Applesoft function for two main reasons. First, only 
a single numeric expression can be passed to the USR subroutine. Second, 
the structure of the internal floating-point accumulator has never been offi- 
cially described by Apple. However, as we shall see in the section below 
entitled ‘Useful Applesoft Built-in Subroutines,’ there are many built-in 
subroutines in Applesoft that can be used to facilitate manipulation of the 
FAC. 


Applesoft’s Built-In Subroutines 


The Applesoft interpreter is made up of many subroutines that are used to 
perform several different functions: evaluating functions, performing arith- 
metic operations, locating variables, handling errors, and so on. Many of 
them make use of the previously described CHARGET subroutine and the 
TXTPTR ($B8) pointer to perform their duties. Table 4-8 describes some of 
the more useful and commonly used Applesoft subroutines. The addresses of 
these subroutines are called “entry points.’ 


Many of the Applesoft subroutines make use of special locations in the //c’s 
zero page. The locations that are referred to in connection with the subrou- 
tines in Table 4-8 are shown in Table 4-9. 


Many of the subroutines contained in Table 4-8 deal with floating-point 
real numbers. Applesoft uses two seven-byte areas in zero page, one from $9D 
to $A3 and the other from $A5 to $AB, to store binary floating-point numbers 
whenever mathematical operations are being performed on real numbers or 
functions are being evaluated. These areas are called the primary floating- 
point accumulator (FAC) and argument register (ARG), respectively. Note 
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Table 4-8. Applesoft built-in subroutines. 


(a) Locating Variables, Data, and Line Numbers 


Address 
Hex (Dec) 
$00B1 (177) 
$00B7 (183) 
$DFE3 (57315) 
$F7D9 (63449) 
$D61A (54810) 


Symbolic Name 


CHARGET 


CHARGOT 


PTRGET 


GETARYPT 


FNDLIN 


Description 


Increments TXTPTR by one position 
and returns the next byte in the pro- 
gram in the A-register. Certain flags 
are also set: if Ais a colon (:’) ora 
zero, then the zero flag is set; other- 
wise, it is cleared. If A is an ASCII 
digit (O” to “9’’), then the carry flag 
is cleared; otherwise it is set. 


Returns the current byte in the pro- 
gram pointed to by TXTPTR in the 
A register. The flags are set in the 
same way as for CHARGET. 


Finds the address of the beginning 
of the data field within the variable 
space for any Applesoft variable. On 
entry, TXTPTR must be pointing to 
the first character of the variable’s 
name. On exit, the address can be 
found in VARPNT ($83/$84) and in 
Y (high) and A (low). 


Finds the address of the name header 
for any array variable. On entry, 
TXTPTR must be pointing to the first 
character in the variable’s name. On 
exit, the address can be found in 
LOWTER ($9B/$9C). 


Locates the line in the program whose 
number is in LINNUM ($50/$51). On 
exit, if the line is found, the carry 
flag is clear and LOWTR ($9A/$9B) 
points to the start of the line. If the 
line was not found, then the carry 
flag will be set and LOWTR will point 
to the next higher line. 


(continued) 
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Table 4-8. Applesoft built-in subroutines (continued). 


(b) Evaluating Formulas 
Address Symbolic Name Description 
Hex (Dec) 
$DD67 (56679) FRMNUM Evaluates a mathematical formula 


and stores the result in the FAC. On 
entry, TXTPTR must be pointing to 
the first character in the formula. On 
exit, the result is placed in the FAC 
unless a syntax error is detected in 
which case an appropriate error 
message is displayed. 


$SE6F8 (59128) GETBYT Evaluates a mathematical formula 
that will yield a result in the range 
@...255. On entry, TXTPTR must 
be pointing to the first character in 
the formula. On exit, the result is 
stored in the X-register and FACLO 
($A1). 


$DD7B (56699) FRMEVL Evaluates a mathematical or string 
formula and stores the result in the 
FAC. On entry, TXTPTR must be 
pointing to the first character in the 
formula. On exit, if a string formula 
is being evaluated, $AQ (low) and $A1 
(high) points to the 3-byte string 


descriptor. 
(c) Converting Num bers 
Address Symbolic Name Description 
Hex (Dec) 
$E2F2 (58098) GIVAYF Converts the 2-byte signed integer in 
A (high) and Y (low) into floating- 
point format and stores it in the FAC. 
$E6FB (59131) CONINT Converts the number in the FAC to 


a single byte integer. On entry, the 
number to be converted must be in 
the FAC. On exit, the single byte inte- 
ger is contained in the X-register and 
FACLO ($A1) unless the result is not 
in the range @... 255 in which case 
an “ILLEGAL QUANTITY ERROR” 
message is displayed. 


(continued) 
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Table 4-8. Applesoft built-in subroutines (continued). 


(c) Converting Numbers 
Address Symbolic Name 
Hex (Dec) 


$E752 (59218) GETADR 


$ED24 (60708) LINPRT 


$ED2E (60718) PRNTFAC 


Description 


Converts the number in the FAC into 
an unsigned 2-byte integer 
(0...65535) in LINNUM ($50/$51). 
If the number is negative, then 65535 
is added to its value. 


Converts the unsigned hexadecimal 
number in X (low) and A (high) into 
a decimal number and displays it. 


Prints the number contained in the 
FAC (in decimal format). The FAC is 
destroyed by this process. 


(d) Applesoft Real-Number Mathematics 


Before executing any of the following subroutines, a number must be loaded 
into the FAC. All of these subroutines first move the number in memory 
pointed to by Y (high) and A (low) into the ARG and perform the mathematical 
operation. The result is placed in the FAC. 


Address Symbolic Name 
Hex (Dec) 


$E7A7 (59303) FSUB 
$E7BE (59326) FADD 
$E97F (59775) FMULT 
$EA66 (60006) FDIV 


(e) Applesoft String Handling 


Address Symbolic Name 
Hex (Dec) 


$E452 (58450) GETSPACE 


Description 


Subtract the FAC from the ARG. 
Add the FAC to the ARG. 
Multiply the ARG by the FAC. 
Divide the ARG by the FAC. 


Description 


Reduces the start-of-strings pointer, 
FRETOP ($6F), by the number spec- 
ified in the A-register (the string 
length) and sets up FRESPC ($71) so 
that it equals FRETOP. After this has 
been done, Aremains unaffected and 
Y (high) and X (low) point to the 
beginning of the space. The string 
can then be moved into place in upper 
memory by using MOVESTR. 


(continued) 
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Table 4-8. Applesoft built-in subroutines (continued). 
(e) Applesoft String Handling 


Address 
Hex (Dec) 
$E484 (58500) 
$E5E2 (58850) 
$ED34 (60724) 
$DB3A (56122) 
$DB3D (56125) 


Symbolic Name 


GARBAGE 


MOVESTR 


FOUT 


STROUT 


STRPRT 


Description 


Clears out old string definitions that 
are no longer being used and adjusts 
FRETOP ($6F) accordingly. (Each 
time that a string is redefined, its old 
definition is kept in memory but is 
not used.) This process is called 
“garbage collection” and is per- 
formed automatically whenever the 
start-of-strings address, FRETOP, 
comes close to the end-of-variables 
address, STREND ($6D). Note that 
under ProDOS this routine is never 
called since BASIC.SYSTEM does its 
own faster garbage collection first. 


Copies the string that is pointed to 
by Y (high) and X (low) and that has 
a length of A to the location pointed 
to by FRESPC ($71). 


Converts the FAC into an ASCII char- 
acter string that represents the num- 
ber in decimal form (like Applesoft’s 
STR$ function). The string is fol- 
lowed by a $00 byte and is pointed 
to by Y (high) and A (low) so that 
STROUT can be used to print the 
string. 


Prints the string pointed to by Y (high) 
and A (low). The string must be fol- 
lowed immediately by a $00 or a $22 
byte. All of these conditions are set 
up by FOUT. 


Prints the string whose 3-byte 
descriptor (a length byte followed by 
a two-byte pointer) is pointed to by 
$AQ0/$A1. FRMEVL sets up such a 
pointer when calculating string for- 
mulas. 


(continued) 
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Table 4-8. Applesoft built-in subroutines (continued). 
(f) Applesoft Real-Number Functions 


In executing the following subroutines, Applesoft expects the argument to be 
in the FAC. After the result has been calculated, it will be placed in the FAC. 


Symbolic Name 


LOG 
ABS 
SOR 
EXP 
COS 
SIN 

TAN 
ATN 


Symbolic Name 


LINGET 


ERROR 


CHKCOM 


Address 
Hex (Dec) 
$E941 (59713) 
$EBAF (60335) 
S$EE8D (61069) 
$EFO9 (61193) 
$EFEA (61418) 
$EFFI1 (61425) 
$FO3A (61498) 
$FO9E (61598) 
(g) Miscellaneous Subroutines 
Address 
Hex (Dec) 
$DAOC (55820) 
$D412 (54290) 
$DEBE (57022) 


Description 


Calculate the natural logarithm 
Calculate the absolute value 
Calculate the square root 
Calculate ‘“‘e to the power of” 
Calculate the cosine (in radians) 
Calculate the sine (in radians) 
Calculate the tangent (in radians) 


Calculate the arctangent (in radians) 
Description 


Loads a line number into LINNUM 
($50/$51). On entry, TXTPTR must 
point to the first digit of the line 
number. 


Handles any Applesoft error condi- 
tions that may occur during the run- 
ning of a program. The subroutine 
first checks ERRFLAG ($D8) to see if 
an ONERR GOTO statement is in 
effect; if ERRFLAG >=$80, then 
error handling has been enabled and 
control passes to the appropriate line 
number. If ERRFLAG <$80, then an 
error message is printed (the error- 
number code is in X) and the pro- 
gram stops. 


Checks that TXTPTR ($B8) is point- 
ing to a comma and, if it is, bumps 
TXTPTR by one. If TXTPTR is not 
pointing to a comma, then a syntax 
error will be generated. 


(continued) 
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Table 4-8. Applesoft built-in subroutines (continued). 


(g) Miscellaneous Subroutines 


Address Symbolic Name ___ Description 
Hex (Dec) 
$E0O0 (57344) COLD Performs an Applesoft cold start (the 
program in memory is destroyed). 
$EOO3 (57347) WARM Performs an Applesoft warm start 
(the program in memory remains 
intact). 


Table 4-9. Some important zero page locations used by Applesoft’s 
built-in subroutines. 


Address 

Hex (Dec) Symbolic Name Description 

$50 (80) LINNUM (low) These are the locations, used by 

$51 (81) (high) GETADR, that contain the result of 
the conversion of the FAC to a 2-byte 
integer. 

$71 (113) FRESPC (low) This is a temporary pointer, used by 

$72 (114) (high) GETSPACE and MOVESTR, that con- 


tains the address of the location to 
which a string is to be moved. 


$83 (131) VARPNT (low) This is a temporary pointer, used by 

$84 (132) (high) PTRGET, that contains the location 
of the data bytes for the last variable 
that was found using PTRGET. 


$9B (155) LOWTR (low) A pointer used by FNDLIN and 
$9C (156) (high) GETARYPT. 


$Al (161) FACLO This is a byte in the FAC that contains 
the result of CONINT and GETBYT. 


$B7 (183) TXTPTR (low) Thisisa pointer to the position within 

$B8 (184) (high) the program that is currently being 
acted on by the interpreter. It is part 
of the CHARGET subroutine. 


$D8 (216) ERRFLAG This is the ONERR GOTO flag. If it’s 
>= $80, then ONERR is active. 
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that despite the use of the words ‘‘accumulator’ and ‘register,’ these are not 
65CQ@2 registers, but merely special data storage areas. Although the format 
Applesoft uses to store numbers in both FAC and ARG is not quite the same 
as the five-byte format used to store real numbers in the Applesoft simple and 
array variable spaces, it will not be described here since knowledge of it is 
not necessary to make use of Applesoft’s built-in floating-point mathematical 
subroutines. 


The FAC is used by Applesoft to hold the argument for those calculations 
that require only one argument (for example, the calculation of a sine). If two 
arguments are required, however, the first argument is kept in the ARG and 
the second is kept in the FAC. In either case, the answer is returned in the 
FAC. 


Remember the Applesoft USR command? The argument that is evaluated 
when this command is executed is stored in the FAC, as is the returned result. 


Using Applesoft’s Built-In Subroutines 


Applesoft’s built-in subroutines can be used in conjunction with your own 
assembly-language programs to greatly simplify those programs and to allow 
you to dispense with having to rewrite programs that have already been 
written. In most cases, it is not even necessary to understand exactly how the 
Applesoft subroutine operates as long as you understand what the entry 
conditions are and what effect the subroutine has on the system. 


There are literally hundreds of useful subroutines within the Applesoft 
interpreter that can be accessed, but only a few of them have been listed in 
Table 4-8. Three of the more important classes of subroutines will be discussed 
in detail here: those used to locate variables, those used to evaluate formulas, 
and those used to convert numbers between different formats. 


Locating Variables 


We have already seen how Applesoft keeps track of its variables and how it 
stores them. Using that information, it would be a fairly simple chore to write 
a program to locate and retrieve any particular one. All you would have to 
do would be to check the name bytes of each variable in the variable table 
that begins at the start of simple variable space until a match was found. 
Applesoft already contains a program to do this, however, so why bother? 
This program is called PTRGET and begins at $DFE3. 


To find the location of a variable, all you must do is adjust TXTPTR ($B8/ 
$B9) so that it points to the first character in the variable name, and then 
execute a JSR PTRGET instruction. When the subroutine ends, VARPNT ($83/ 
$84) will contain the address of the beginning of the variable’s data field. 
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PTRGET can be used to simplify the passing of Applesoft variables to and 
from an assembly-language program. Variables are usually passed by tacking 
their names, separated by commas, on toa CALL or & command. For example, 
to pass two variables, say F% and L%, to a program starting at $300, you 
could use the following command: 


CALL 768,F%,L% 


Immediately after the CALL 768 command is executed, TXTPTR is pointing 
to the location occupied by the comma separator. Before we can use PTRGET, 
TXTPTR must be advanced by one position. This is done at the beginning of 
the subroutine being called by using a subroutine called CHKCOM ($DEBE) 
that ensures that the current character is indeed a comma, and then incre- 
ments TXTPTR. Once this has been done, everything is ready for a call to 
PTRGET. After it has been called, VARPNT ($83/$84) can be examined to 
determine where the data for that variable is located. Since the storage format 
of the data is known, it is a simple matter to read and interpret it. In summary, 
the method to be used to locate a variable is as follows: 


JSR CHKCOM ;okip over the ",* separator 

JSR PTRGET ;Find the variable and put ptr 
in VARPNT 

LDY #@ 

LDA CVARPNT),Y ;Get first byte of variable’s 
data 

INY 

LDA CVARPNT),Y ;Get second byte of variable’s 
data 


After PTRGET has been called, TXTPTR points to the byte after the last 
character of the variable’s name. This means that you would perform another 


JSR CHKCOM 
JSR PTRGET 


sequence to retrieve the next variable specified after the CALL statement. 


Let's look at a complete example to see how to use these subroutines. Table 
4-10 shows a program called UPPER that is designed to convert any lowercase 
characters in a string variable to their corresponding uppercase characters. 


Once the program has been installed, it can be called from Applesoft as 
follows: 


CALL 768,A$ 
where A$ is the string variable to be modified. 


Notice how the program works. The first step is to skip over the comma by 
calling CHKCOM. After that has been done, TXTPTR will be pointing to the 
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“A” in A$ and PTRGET can be called to locate the three data bytes used to 
describe the string (one byte for the length and two bytes representing its 
location). The pointer to the first of these three bytes is automatically stored 
in VARPNT ($83/$84), so that the three bytes can be examined by using 
indirect indexed instructions as follows: 


LDA CVARPNT),Y 


where Y=@,1,2. After the length and pointer have been determined, it is a 
simple task to scan through the bytes in the string to see whether their ASCII 
codes are between those for ‘‘a” and “z’’ and, if they are, to convert them to 
uppercase by performing an AND #$DF operation. (This essentially subtracts 
32 from the lowercase ASCII code, thus converting it to the corresponding 
uppercase ASCII code.) If you print A$ after calling UPPER, you will see that 
all of its lowercase characters have, indeed, been converted to uppercase. 


Evaluating Formulas 


Not surprisingly, there are also several built-in Applesoft subroutines that 
can be used to evaluate mathematical formulas. Again, you could write such 
programs yourself, but they would need to be exceedingly complex and would 
be difficult to develop. 

The main Applesoft subroutine for evaluating a mathematical formula is 
called FRMNUM and is located at $DD67. To use it, you must first ensure 
that TXTPTR is, as usual, pointing to the location of the first character in the 
formula. Once this has been done, FRMNUM can be called; after this subrou- 
tine has finished executing, the result of the calculation will be stored in the 
FAC. You can then use other built-in subroutines to massage this number as 
you see fit, for example, to print it out or to convert it to an integer. 


Let's look at an example of the use of FRMNUM. The program in Table 4- 
11, called FORMULA, evaluates any mathematical formula that is passed to 
it and displays the result. To CALL it from Applesoft, you must enter the 
command 


CALL 768,aexpr 


where ‘“‘aexpr’’ represents the Applesoft formula that is to be evaluated. 


The first part of the program should look familiar. It is the ‘‘standard” JSR 
CHKCOM instruction that skips over the comma after the CALL statement. 
Once this has been performed, the formula can be evaluated by a JSR FRMNUM 
and the result will be placed in the primary FAC. To see the result it is simply 
necessary to perform a JSR PRNTFAC ($ED2E). 


Converting Numbers 


Number conversion plays an important role in the Applesoft interpreter. 
Numbers are normally handled internally in a binary format, but whenever 
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they are to be displayed they must be converted to more recognizable decimal 
numbers. Conversely, numbers that are inputted, say from the keyboard by 
a user, are normally inputted in decimal form and must be converted to 
binary form before they can be processed. 


In addition to the above types of conversions, it is often necessary to convert 
an integer number to a floating-point number and vice versa. This is handled 
by the Applesoft GIVAYF subroutine and by the CONINT or GETADR sub- 
routines, respectively. The latter two subroutines are especially useful because 
quite often only integer quantities are being manipulated and, as we have 
seen, whenever a formula is evaluated by performing a JSR FRMNUM, the 
result is placed in the FAC, which is difficult to interpret. By using CONINT 
or GETADR, the FAC can be quickly converted to an easy-to-handle one- or 
two-byte integer format. 


The program in Table 4-12, CONVERT, shows how the CONINT subroutine 
can be used to convert the contents of the FAC to a one-byte integer in the 
range @...255. As usual, CONVERT is designed to be called from Applesoft, 
using the command 


CALL 768,aexpr 


where “‘aexpr’’ represents a mathematical formula that will evaluate into an 
integer within the @... 255 range. 


The first step is to skip over the comma with a JSR CHKCOM. Then, the 
formula is evaluated and placed in the primary FAC with a JSR FRMNUM. 
At this stage, we would like to convert the FAC into an easier format to handle: 
a one-byte number. This is done by executing a JSR CONINT; after CONINT 
has been executed, the one-byte number will be found in the X register. 
CONVERT then stores the value in the X register at location $6 where it can 
be read with an Applesoft PEEK (6) command. 


If the integer result is going to be larger than 255, then GETADR must be 
used instead of CONINT. After a JSR GETADR, the value of the integer will 
be contained in LINNUM ($50/$51), so that the decimal result will be 
PEEK(80) + 256* PEEK(81). 
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Further Reading for Chapter 4 


Standard reference works... 


Applesoft BASIC Programmer's Reference Manual, Volumes 1 and 2, Apple 
Computer, Inc., 1982. 


All About Applesoft, Call -A.P.P.L.E., 1981. A useful source of internal infor- 
mation about Applesoft. 


BASIC Programming with ProDOS, Apple Computer, Inc., 1983. 
On Applesoft entry points... 


J. Crossley, ‘“Applesoft Internal Entry Points’, Apple Orchard, March/April 
1980. The seminal work on Applesoft entry points. Unfortunately, it con- 
tains numerous typographical errors and incorrect addresses—these cor- 
rections have been made in a reprint of the article which appears in “All 
About Applesoft’’, above. 


R.M. Mottola, “Applesoft Floating Point Routines’, Micro, August 19890, p. 
53. A detailed look at Applesoft’s built-in subroutines that support real- 
number mathematics. 


C. Bongers, ‘‘In the Heart of Applesoft’’, Micro, February 1981, p. 31. A 
comprehensive look at the internals of the Applesoft interpreter. 


“Using Applesoft ROMs from Assembly Language’’, Apple Assembly Line, 
November 1981, pp. 2-13. More on accessing Applesoft’s built-in subrou- 
tines. 


C. Bongers, Applesoft's CHARGET Routine, Call -A.P.P.L.E., March 1982, p. 
21. Suggestions for improvements to CHARGET. 


B. Sander-Cederlof, “All About PIRGET & GETARYPT”, Apple Assembly 
Line, March 1983, pp. 2-9. A look at two useful entry points to Applesoft. 


On Applesoft data storage ... 


V. Golding, ‘‘Applesoft From Bottom to Top”, Call -A.P.P.L.E., March 1979, 
p.3. A look at the internal structure of Applesoft. A revised version of this 
article appears in “‘All About Applesoft’’, above. 


G.A. Lyle, ‘Float, Float, Float Your Point (F.P. Representation)’, Apple 
Orchard, Winter 1980, pp. 37-39. A description of how Applesoft stores 
real variables. 


E.E. Goez, “Real Variable Study”, Call -A.P.P.L.E., January 1981, pp. 8-23. 
A detailed look at how Applesoft deals with real variables. A revised 
version of this article appears in ‘‘All About Applesoft’’, above. 


C.K. Mesztenyi, “Applesoft Internal Structure’, Call -A.P.P.L.E., January 
1982, p.9. 


A. Moss, “‘Playing With Program Pointers”, Nibble, Vol. 4, No. 3 (1983), pp. 
69-81. A look at the various Applesoft pointers. 
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On linking to assembler language ... 


B. Sander-Cederlof, ““Using USR fora WEEK”, Apple Assembly Line, October 
1982, p. 30. A program is presented which uses USR to calculate the value 
of a two-byte pointer. 


D. Lingwood, “The Return of the Mysterious Mr. Ampersand”, Call -A.P.P.L.E., 
May 1980, p.26. Examples of uses for the & command. 
Source Code for the Applesoft interpreter ... 


Available from: 


(1) Roger Wagner Publishing, P.O. Box 582, Santee, CA 92071 
(comes with and requires Merlin Assembler). 


(2) S-C Software Corporation, P.O. Box 280300, Dallas, TX 75228 
(requires S-C Macro Assembler). 


The ProDOS Disk 
Operating System 


The disk drive is the primary mass storage device used by the //c. It can be 
used to quickly and reliably access units of information (called “files’’) that 
are stored on standard 5.25-inch floppy diskettes. These files can contain 
programs, data, readable text, or any other type of information. 


Information is passed to and from a diskette by using special disk operating 
system (DOS) commands that are available for use by an Applesoft program 
after a DOS diskette is first started up (“booted”’). Assembly-language pro- 
grams can access the diskette by calling documented DOS subroutines. The 
DOS that comes with the //c is called ProDOS and we will be examining it in 
detail in this chapter. 


ProDOS was first released by Apple in January 1984 for use with its Apple 
II family of computers. ProDOS is intended to be the successor to Apple's 
older disk operating system (called DOS 3.3). DOS 3.3 is essentially the same 
operating system that has been in use since Apple first introduced its disk 
drive peripheral for the original Apple I] in 1978. 


The //c comes with a built-in disk drive that is functionally identical to the 
Apple Disk II drives that are used on the Apple //e, Apple II Plus, and Apple 
II. A second disk drive can also be added by attaching it to the special disk 
port at the back of the //c. 


The built-in disk drive is the //c’s port 6 device. The diskette in this drive 
will automatically boot when the power to the //c is turned on. Alternatively, 
you can boot it by entering a ‘‘PR#6” command from Applesoft direct mode, 
a ‘6[control-P]”” command from the system monitor, or by pressing [control- 
OPEN- APPLE-RESET] at any time. 


The external drive is sometimes interpreted as a port 7 device, but ProDOS, 
for DOS 3.3 compatibility reasons, considers it to be drive 2 of the port 6 
device. This means that the external drive cannot be booted using a ‘“PR#7”’ 
command, as you might otherwise expect. However, you can use the system 
monitor ‘‘7[control-P]’’ command to boot it. 


The primary purpose of this chapter is not to teach you how to use the 


115 


116 [ _] Inside the Apple //c 


ProDOS commands but rather to explain the methods used by ProDOS to 
organize information on diskettes and to provide you with an insight into the 
internal operation of ProDOS. Let’s get started right now. 


Formatting Diskettes 


Before a diskette can be used by ProDOS it must be formatted into a state 
that ProDOS recognizes. (To do this, select the ‘“FORMAT A DISK” command 
in the program found on Apple’s System Utilities diskette for the //c.) When 
you format a diskette, templates for 35 ‘‘tracks” on the diskette are created 
(numbered from @ to 34), each of which can hold 4096 bytes of information. 
These tracks are arranged in concentric rings around the central hub of the 
disk, with track @ being located at the outside edge and track 34 at the inside 
edge. ProDOS can access any track by causing a special read/write head 
(located inside the disk drive) to move over the desired track. This is done 
using I/O locations that activate a small motor (called a “stepping” motor) 
that controls the motion of a metal arm to which the read/write head is 
connected. This arm moves along a radial path beginning at the outside edge 
of the diskette (track 0) and ending at the inside edge (track 34). 


Each of the 35 tracks that are formatted on a diskette are subdivided into 
sixteen smaller units called “sectors.” The sectors that make up a track are 
numbered from @ to 15 and each can hold exactly 256 bytes of information. 
If you do the mathematics, you will quickly determine that a diskette can 
hold 560 sectors (140K) of information. 


Note, however, that when ProDOS organizes files on a diskette it uses the 
512-byte block as the basic unit of file storage; each block is made up of two 
sectors. An initialized diskette is considered to be made up of 280 blocks 
(numbered from @...279), but it is rarely necessary to know where these 
blocks are actually located on the diskette since ProDOS assigns block num- 
bers to physical locations internally. 


ProDOS Memory Map 


When a ProDOS diskette is first booted, a file called PRODOS is loaded into 
memory and executed (it is a ProDOS “system” file). This file contains the 
fundamental I/O subroutines that are used to read and write blocks of data 
from and to the diskette. PRODOS then loads and executes another system 
file into memory; the one loaded has a name of the form xxxx.SYSTEM (the 
first file having such a name when the disk is catalogued will be used). 


If an Applesoft programming environment is to be supported, this file must 
be BASIC.SYSTEM (it is found on the ProDOS system diskette). As we will 
see below, BASIC.SYSTEM contains the subroutines that “add” the standard 
ProDOS commands to the Applesoft programming language. It also takes care 


5 / The ProDOS Disk Operating System [| 117 


of parsing these commands, doing syntax checking, and calling the PRODOS 
I/O subroutines when required. For convenience, we will be referring to the 
resultant PRODOS-BASIC.SYSTEM program combination as ‘‘ProDOS” even 
though this is technically not the case. 


After ProDOS has been loaded as described, it will occupy the following 
memory locations: 
@ $9A00-$BFFF in main RAM 


® $D000-$DFFF in bank1 of main bank-switched RAM and $D100- to $D3FF 
in bank2 of main bank-switched RAM 


@ $E000-$FFFF in main bank-switched RAM 

(See Chapter 8 for a discussion of bank-switched RAM.) In addition, a 
general-purpose file buffer will be set up from $9600 to $99FF and the Apple- 
soft HIMEM location will be set equal to $9600. (HIMEM refers to the value 
of the Applesoft end-of-string pointer at $73/$74—-see Chapter 4.) Thus, the 
area used for storage of Applesoft string variables will not conflict with areas 
used by ProDOS. 


The $400-byte buffer just above Applesoft HIMEM is always used by ProDOS 
as a buffer for directory blocks whenever the diskette is CATALOGued. This 
buffer does not always begin at $9600, however, since HIMEM could be 
changed in the following instances: 


@ By using the Applesoft HIMEM: command or the GETBUFR ($BEF5) 
subroutine in BASIC.SYSTEM 


@ By opening and closing diskette files using the PPoDOS OPEN and CLOSE 
commands 


The Applesoft HIMEM: command simply places the address specified after 
the command directly into the HIMEM pointer. 


The GETBUFR ($BEF5) subroutine can be called from an assembly- lan- 
guage program if you want to lower HIMEM by a given number of 256-byte 
pages. To do this, call GETBUFR with the number of pages in the accumu- 
lator; upon exit, the carry flag will be clear if there was enough free space to 
lower HIMEM, or it will be set if there wasn't. 


It is not immediately obvious how or why the OPEN and CLOSE commands 
affect the value of HIMEM. Whenever a file is opened, ProDOS creates a $400- 
byte file buffer by moving HIMEM down in memory by that number of bytes 
and then reserving the- $400 byte area beginning at the original HIMEM 
position for use by the file. Whenever a file is closed, HIMEM is moved up by 
$400 bytes. While doing all this, ProDOS takes all steps necessary to ensure 
that Applesoft’s string variables are not overwritten. 


It is often convenient to reserve a safe area of memory where assembly- 
language programs can be stored without fear of being overwritten by either 
ProDOS or Applesoft. In DOS 3.3 days, such an area could be reserved simply 
by lowering HIMEM and then storing the program between the new and old 
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HIMEM addresses. You can’t do this with ProDOS, however, because of the 
way HIMEM changes when files are opened or closed. When ProDOS is being 
used, however, a safe area can be reserved that resides just above the $400- 
byte directory buffer that sits above HIMEM. The steps that must be followed 
to do this are as follows: 


@ Close all files using the ProDOS CLOSE command. 


@ Lower HIMEM by a multiple of $100 (256) bytes using the Applesoft 
HIMEM: command or the GETBUFR ($BEF5) subroutine. 


If you are using the HIMEM: command to lower HIMEM, these steps must 
be performed before any Applesoft variables have been defined, since the 
Applesoft string space will be overwritten. After these two steps have been 
completed, the area from HIMEM + $400 to $99FF can be used for storage of 
machine-language programs without danger of having them overwritten by 
ProDOS operations. 


Keep in mind one important restriction that applies when using ProDOS: 
if HIMEM is being changed (that is, the $73/$74 end-of-string pointer is being 
changed), it must be changed in multiples of 256 bytes only! You can’t go 
wrong if you use GETBUFR, of course, since it can only be used to lower 
HIMEM by page multiples. Be very careful, however, when you use the Apple- 
soft HIMEM: command, because Applesoft does not check to see that the 
address specified in the command is an integral multiple of 256. 


ProDOS Page 3 Vectors 


Apple has reserved the entire area from $3D0...$3EF for use by ProDOS 
even though the current version (1.1) uses only the first six locations. As 
indicated in Table 5-1, these six locations hold two JMP instructions to the 
warm-start entry point of ProDOS (location $BEQQ). 


ProDOS also initializes all of the system vectors that appear in page 3 from 
$3FO ...$3FF. These are the interrupt vectors for BRK, Reset, IRQ, and NMI 
(see Chapter 2), the vector for the system monitor's [control-Y] USER com- 
mand (see Chapter 3), and the vector for the Applesoft & command (see 
Chapter 4). Descriptions of all the vector subroutines installed by ProDOS 
are given in Table 5-2. 


Filenames and Pathnames 


When a file is stored on a diskette, it is assigned a unique filename that is 
used to identify it thereafter. A ProDOS filename can be up to 15 characters 
long. It must begin with an alphabetic letter (A—Z), but the other characters 
may be any combination of letters, digits (@—-9), and periods (.). Lowercase 
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Table 5-1. ProDOS page 3 vectors. 


Address Description of Vector 


$3D0-$3D2 AJMPinstruction to the ProDOS warm-start entry point. A call 
to this vector will reconnect DOS without destroying the Apple- 
soft program in memory. Use the ‘“3D@G”’ command to move 
from the system monitor to Applesoft. 


$3D3-$3D5 Another JMP instruction to the ProDOS warm-start entry point. 


letters may also be used, but ProDOS automatically converts them to upper- 
case. Here are some examples of valid ProDOS filenames: 


CRACKED.WHEAT 
CANNED.HEAT 
MY .PROGRAM 


When a file is saved to diskette, it can be stored in any one of several 
‘directories’ that can be created on the diskette. These directories are some- 
what analagous to file folders in that they are usually used to hold groups of 
related files. For example, you may use one directory to hold word processing 
documents, another to hold Applesoft programs, and so on. The ability to 
create separate directories on a diskette makes it easier to deal with large 
numbers of files. 


When a diskette is first formatted, only one directory, called the ‘‘volume”’ 
directory, exists; you name the volume directory when the diskette is for- 
matted (the rules for naming directories are the same as for naming files). 
You can create additional directories (called ‘‘subdirectories’’) within the 
volume directory using the ProDOS CREATE command. Indeed, you can even 
create subdirectories within subdirectories (up to 64 levels are permitted). 


The directory in which a file is to be saved is normally specified by tacking 
on a special prefix to the filename to create a unique identifier called a 
“pathname.” A pathname is made up of the names of a series of directories, 
beginning with the name of the volume directory and continuing with the 
names of all the directories that must be passed through to reach the directory 
you want, followed by the filename itself; each directory name is separated 
from the next by a slash (‘‘/”’) and a slash must precede the name of the volume 
directory. The list of directory names must define a continuous path: each 
directory specified must be contained within the preceding directory. 


For example, consider a diskette that has a volume directory called BASE- 
BALL and two subdirectories within BASEBALL called AMERICAN and 
NATIONAL. If you want to save a file called NY. YANKEES in the AMERICAN 
subdirectory, then you would specify the following pathname: 


/BASEBALL/AMERICAN/NY. YANKEES 
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Table 5-2. Initialization of page 3 system vectors by ProDOS. 
Vector Name Address __ Contents Description 


BRK $3FQ-$3F1 $FA59 Address of a subroutine to that 
displays the 65C@2 registers 
and then enters the system 


monitor. 
RESET $3F2-$3F3 $BEQ0O Address of the ProDOS warm- 
start entry point (reconnects 

ProDOS). 
& $3F5-$3F7 “JMP$BE03” Jump to ProDOS’s external 


entry point for command 
strings (see Apple’s ProDOS 
Technical Reference Man- 
ual). 


USER $3F8-$3FA “JMP$BE00" Jump to ProDOS’s warm-start 
entry point. 

NMI $3FB-$3FD “JMP$FF59" Jump tothe system monitor's 
cold-start entry point. 


IRQ $3FE-$3FF $BFEB Address of the special ProDOS 
interrupt handler (see Chap- 
ter 2). 


Note: The addresses stored at each vector location are stored with the low-order byte 
first. 


If you simply specified NY.YANKEES, then the file would be saved in the 
currently active directory, which is usually the volume directory (unless it 
has been changed using the PREFIX command that we are about to describe). 


If all files of interest are contained in the same subdirectory, it becomes 
annoying to have to specify the same chain of directory names leading up to 
the file every time one is to be used. To alleviate this annoyance, ProDOS 
supports a PREFIX command that can be used to set the chain of directory 
names to which any filename specified in a ProDOS command will be auto- 
matically appended. For example, if PREFIX is set by entering the following 
ProDOS command: 


PREF IX/BASEBALL/AMERICAN/ 


then any file contained in the directory at the end of this path (AMERICAN) 
can be referred to by entering its filename only. A name that is a continuation 
of the prefix could also be entered to access files in lower-level subdirectories; 
such a name is called a “partial pathname.” If PREFIX is set as just described 
and if AMERICAN contains a subdirectory called CHAMPS which contains a 
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file called TIGERS.1984, then you would access the file by specifying a partial 
pathname of CHAMPS/TIGERS.1984. 


The advantage of subdirectories is often not readily apparent to users of 
floppy diskettes, but becomes obvious when a hard disk system is used where 
there is enough room to hold thousands of files. If all the files were held in 
one directory you might have to wait a long time to spot your file when the 
disk was catalogued, and even then you could well miss it amidst the multi- 
tude of other files. Fortunately, the hierarchical directory structure provided 
by ProDOS allows related files to be grouped within the same subdirectory 
for easy access. 


By the way, when ProDOS is first booted, it treats the 64K of auxiliary 
memory as if it was storage space on a diskette and assigns it the volume 
directory name of /RAM. A total of 119 blocks on this volume are available 
for file data storage. The /RAM volume can be used to load and save programs 
extremely quickly since “I/O” operations involve nothing more than the move- 
ment of data between memory locations; no slow mechanical parts need be 
controlled. Remember, however, that any information stored in the /RAM 
volume will disappear as soon as the //c is turned off or when ProDOS is 
rebooted. If you want to permanently save any files on the /RAM volume, you 
must transfer them to a diskette first. 


BASIC.SYSTEM Commands 


After ProDOS (version 1.1) is booted and the BASIC.SYSTEM system pro- 
gram is executed, 31 commands become available for use within an Applesoft 
program (many can also be used from Applesoft direct mode). Most of these 
commands provide ready access to files for I/O operations (OPEN, READ, 
POSITION, WRITE, APPEND, FLUSH, and CLOSE), or general file manage- 
ment (CAT, CATALOG, CREATE, DELETE, LOCK, PREFIX, RENAME, 
UNLOCK, and VERIFY), or program file loading and execution (-, BLOAD, 
BRUN, BSAVE, EXEC, LOAD, RUN, SAVE) There are also commands used 
to effect I/O redirection (IN#, PR#), to perform garbage collection of Applesoft 
variables (FRE), to save and load Applesoft variables to and from files (STORE 
and RESTORE), to transfer control from one Applesoft programs to another 
without destroying existing variables (CHAIN), and to disconnect 
BASIC.SYSTEM and run a ProDOS system program (BYE). 


To use an Applesoft command from within a program, you must use the 
PRINT statement to print a [control-D] character, the ProDOS command, the 
command arguments, and then a carriage return. For example, to list all the 
files in the //c’s /RAM volume, you would execute a line that looks something 
like this: 

180 PRINT CHR$C4);"CATALOG/RAM" 


In this example, the CHR$(4) statement generates the [control-D] character, 
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the ProDOS command is CATALOG, and the command argument is /RAM. 
The required carriage return is automatically generated by the PRINT state- 
ment. 


If you’re entering a ProDOS command directly from the keyboard in Apple- 
soft direct mode, then you don't have to worry about the [control-D]. All that 
you have to do is type in the command followed by the command arguments. 
The keyboard equivalent of the CATALOG command is simply 


CATALOG/RAM 


You should be aware, however, that ProDOS does not permit all of its 
commands to be entered from the keyboard in this way. 


Most of the ProDOS commands accept an argument that is simply the file- 
name, pathname, or partial pathname of the file that is to be acted on. The 
major exceptions are the PR#, IN#, and FRE commands. 


Let’s take a quick look at each of the 31 ProDOS commands right now. (You 
can refer to Apple’s manual, “BASIC Programming with ProDOS”, for detailed 
information on these commands.) They can be divided into four distinct 
categories: file management commands, file loading and execution com- 
mands, file input/output commands, and miscellaneous commands. 


File Management Commands 


CAT. This command is used to display a list of the names of the files on 
the diskette. Only the names of the files in the directory specified in the 
argument following the CAT command will be displayed (if no argument is 
specified, then the currently active directory will be used). CAT will also 
display the type of each file (as a three-character mnemonic such as BAS, 
BIN, TXT, SYS, and so on; see Table 5-6), the number of blocks it occupies, 
and the date on which it was last modified. 


CATALOG. This command is very similar to CAT. It displays the very 
same information for each file as well as its time of last modification, its 
creation date and time, its size (in bytes), and its ‘subtype’ entry (which is 
either the default loading address for a binary file or the record length for a 
textfile). 


CREATE. This command is used to create a file on the diskette. It is most 
often used to create subdirectory files since the other common types of ProDOS 
hles (Applesoft programs, binary files, and text files) are automatically created 
by other ProDOS commands (SAVE, BSAVE, and OPEN). For example, if the 
volume directory is active and you want to create a subdirectory called 
DEMO.PROGRAMS, then you would enter the command 


CREATE DEMO.PROGRAMS 


from the keyboard. When you do this, the subdirectory will appear as a file 
entry when you catalog the directory in which it is contained. The file type 
mnemonic used to identify it in the catalog listing is DIR. 
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DELETE. This command is used to erase a file from the diskette. Only 
unlocked files can be erased with the DELETE command. (See the description 
of the LOCK command.) 


LOCK. This command is used to protect a ProDOS file from accidental 
deletion or modification. Once a file has been locked, it cannot be deleted or 
modified unless it is first unlocked. You can tell which files on a diskette are 
locked by cataloguing the diskette (using the CAT or CATALOG commands); 
if the name of the file is preceded by an asterisk (“‘*’’), it is locked. 


PREFIX. This command is used to define the chain of directory names to 
which any filename or partial pathname specified will automatically be 
appended to generate the full pathname (see above). It is this pathname on 
which the ProDOS commands will act. 


RENAME. This command is used to change the name of any file on the 
diskette. 


UNLOCK. This command unlocks a file that is locked. 


VERIFY. This command checks to see if a file exists on the diskette. If it 
doesn't, an error message will be displayed. 


File Loading and Execution Commands 


-(dash). This is the ProDOS “intelligent” run command. Its argument can 
be the name of an Applesoft program, a binary program, or a textfile, in which 
cases the - will behave exactly like a RUN, BRUN, or EXEC command, 
respectively. 


BLOAD. This command is used to transfer the data from a file to a contig- 
uous block of memory. The most common form of this command is: 


BLOAD MY.FILE,Aaddr 


where “addr” is the address of the beginning of the block to which the file is 
to be transferred. ‘‘addr’’ can be a decimal or hexadecimal number; as usual, 
hexadecimal addresses are preceded by “$.”” The BLOAD command can also 
be used without the “,Aaddr’”’ suffix; in this case, the file will be loaded at the 
location from which it was originally saved to diskette using the BSAVE 
command (this address appears in the “subtype” column when the diskette 
is catalogued using the CATALOG command). 


BRUN. This command is the same as BLOAD except that after the file is 
loaded, it will automatically be executed. Execution begins at the loading 
address. 


BSAVE. This command is used to save the contents of a range of memory 
to a file. (The default file type used is binary (BIN) but you can override this 
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default.) For example, to save the contents of memory from $300 to $3CF to 
a binary file called PAGE.THREE, you would enter the command: 


BSAVE PAGE.THREE ,A$300,E$3CF 
or 


BSAVE PAGE.THREE ,A$300,L$D0 


where the “‘,A$300”’ suffix indicates the starting address of the range, ‘,E$3CF”’ 
indicates the ending address, and “,L$DQ@” indicates the number of bytes to 
be saved. You can also use decimal numbers to specify addresses and numbers. 


EXEC. This command is used to redirect subsequent requests for input to 
the specified file instead of the keyboard until everything in the file has been 
read. For example, suppose you have defined a file called MY.STARTUP that 
contains the following two lines: 


HOME 
CATALOG 


When you enter EXEC MY.STARTUP from direct mode, the screen will clear 
and then the diskette will be catalogued, just as if you had entered the two 
commands directly from the keyboard. 


LOAD. This command is used to load an Applesoft program into memory 
from a file. 


RUN. This command is the same as the LOAD command except that after 
the program is loaded, it will automatically be executed. 


SAVE. This command is used to save an Applesoft program to a file. The 
file type mnemonic for a program file is BAS. 


File Input/Output Commands 


OPEN. This command is used to open a file, usually a textfile, for either 
reading or writing. If the filename specified does not exist, then a new file will 
be created. A file must be opened before it can be accessed using the ProDOS 
READ, WRITE, APPEND, FLUSH, and POSITION commands. Textfiles can 
be opened as one of two basic types: sequential or random-access. A sequential 
textfile is one in which in which lines of information are stored one after 
another, with no gaps in between; usually, if you want to access information 
anywhere in the file, you have to read all the information that precedes it. 


A random-access file is one that is organized as a series of fixed-length 
records that hold related groups of information; any record can be accessed 
“randomly” (that is, without reading all previous records first) simply by 
specifying its record number when using the READ command. The record 
length is assigned to a random-access textfile when it is first created or opened; 
it is displayed in the subtype column of a CATALOG listing in the form 
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“R=$xxxx.” For example, if the record length is 127, then the subtype entry 
would be “R= $007F.’’ 


READ. This command is used to redirect subsequent requests for input to 
an open file instead of the keyboard. 


POSITION. This command is used to adjust the position in the file at 
which subsequent read and write operations will operate. 


WRITE. This command is used to redirect subsequent output to an open 
file instead of to the video screen. 


APPEND. This command is used to open a file and to redirect subsequent 
output to the end of it. 


FLUSH. When a ProDOS file is opened, a 512-byte file buffer is allocated 
to it in memory. Data that is written to the file is not normally stored to disk 
until this buffer becomes full; when it does, the buffer is saved to disk and 
then it is cleared. The FLUSH command is used to force any data stored in 
the buffer to be saved to diskette even if the buffer is not yet full. This 
minimizes the risk of data loss in the event of an unexpected exit from the 
program (caused by a loss of power, pressing RESET, and so on) but it slows 
down diskette write operations considerably. 


CLOSE. This command is used to close a file that has been opened using 
the OPEN command. 


Miscellaneous Commands 


BYE. This command is used to.disconnect BASIC.SYSTEM and execute a 
ProDOS system program. When the command is entered, you will be prompted 
to enter the prefix and partial pathname of the system program. After you do 
this, the program will be executed. 


CHAIN. This command is used to transfer control from one Applesoft pro- 
gram to another while maintaining the names and current values of all the 
variables in the program from which control is being passed. This allows very 
large programs to be executed on the //c by breaking them into separate 
modules and chaining them together. 


FRE. This command is used to force garbage collection of Applesoft string 
variables. (See Chapter 4 for a description of this procedure.) This garbage 
collection command is much faster than the one built in to the Applesoft 
interpreter. 


IN#. This command is used to redirect subsequent requests for input to a 
port or to a specified memory location. (See Chapter 6.) 


PR#. This command is used to redirect subsequent output to a port or to 
a specified memory location. (See Chapter 7.) 
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RESTORE. This command is used to initialize the names and values of 
the variables in an Applesoft program to those contained in the file specified 
in the argument. This file must be of type VAR (this is the type created by the 
STORE command). 


STORE. This command is used to save the names and current values of 
all the variables in an Applesoft program to a file. The mnemonic for the file 
type code assigned to the file is VAR. 


ProDOS File Storage 


We are now ready to examine the method that ProDOS uses to store infor- 
mation on a diskette. This will include an analysis of the structures of the 
directories that hold information concerning files, of the volume bit map that 
keeps track of block usage on the diskette, and of the index blocks that are 
used to locate the data blocks that are used by each file. We'll also see how to 
read and write blocks on the diskette using internal ProDOS subroutines. 


Before we continue, keep in mind that the descriptions that follow relate 
to ProDOS only and not to its predecessor, DOS 3.3.; the older DOS 3.3 
organizes files on a diskette in a less efficient, and wholly incompatible, 
manner. A utility program called CONVERT is included with ProDOS, how- 
ever, that allows most files to be transferred between DOS 3.3 and ProDOS 
formatted diskettes so that they can be used by either operating system. 


Volume Bit Map 


Of the 280 blocks on a ProDOS diskette, the first seven (numbered from @ 
to 6) are reserved for specific purposes. Blocks @ and 1 contain a program that 
is loaded into memory whenever the diskette is booted. This program is called 
the bootstrap loader and is responsible for loading and executing the PRODOS 
system file. Blocks 2 through 5 represent the four blocks that contain the 
volume directory information and will be described in the next section. Block 
6 contains the volume bit map for the diskette. 


The volume bit map is used to keep track of which areas of the diskette are 
in use and which are free. Only the first 35 bytes (280 bits) in the volume bit 
map block are actually used and each bit in each byte corresponds to a unique 
block number. The byte number (from @ to 34), and the bit number within 
that byte (from @ to 7), that corresponds to any given block number (from @ 
to 279) can be calculated using the following Applesoft formulas: 


BYTENUM = INTCBLOCKNUM/8) 
BITNUM = 7 - BLOCKNUM - 8 * BYTENUM 


If the bit associated with a particular block is one, then that block is free. 
If it is zero, then it is being used by a file on the diskette. 


5 / The ProDOS Disk Operating System [| 127 
Diskette Directory 


As was explained earlier, ProDOS allows multiple directories to be created 
on one diskette. With the exception of the volume directory (the one through 
which all the others must be accessed), these directories can be stored just 
about anywhere on the diskette since they are treated similarly to standard 
files. The volume directory, however, is always located in blocks 2 through 5 
of the diskette. 


Each block used by any directory can hold up to thirteen 39-byte file entries. 
(This means that the four-block volume directory can hold a total of 52 entries, 
one of which is the volume name entry.) These entries completely describe 
the files by specifying the name, type, and size of the file. The map of a 
directory block is shown in Table 5-3. 


The first block used by a directory (or subdirectory) is called the “key block” 
and is configured slightly differently than the others. The 39-byte entry that 
normally describes the first file in the block is instead used to describe the 
directory itself. This entry is called the directory header. 


Table 5-3. Map of a ProDOS directory block. 


Byte number in 
Directory Block Meaning of Entry 


$000-$001 Block number of the previous directory block (low byte 
first). This will be zero if this is the first directory block. 

$002-$003 Block number of the next directory block (low byte first). 
This will be zero if this is the last directory block. 

$004-$02A Directory entry for file #1 OR, if this is the first block of 
the directory (bytes $00 and $@1 are @), the directory header. 

$02B-$051 Directory entry for file #2 

$052-$078 Directory entry for file #3 

$079-$09F Directory entry for file #4 

$0A0-$0C6 Directory entry for file #5 

$0C7-$0ED Directory entry for file #6 

$QEE-$114 Directory entry for file #7 

$115-$13B Directory entry for file #8 

$13C-$162 Directory entry for file #9 

$163-$189 Directory entry for file #10 

$18A-$1B0 Directory entry for file #11 

$1B1-$1D7 Directory entry for file #12 

$1D8-$1FE Directory entry for file #13 


$1FF <Not used> 


128 [| Inside the Apple //c 
The meaning of each of the 39 bytes that make up a directory header are 


shown in Table 5-4. Notice the differences between the header for a volume 
directory and the header for a subdirectory. 


Table 5-4. Map of a ProDOS directory header. 


Byte number Description (usual entries in parentheses) 
in Key Block 
$04 High four bits: storage type 
—$Q@F for a volume directory 
—$@0E for a subdirectory 
Low four bits : length of directory name 
$05-$13 Directory name (in ASCII). The length of the name is con- 
tained in the low-order half of byte $04. 
$14—$1B <Reserved> 
$1C-$1D The date on which this directory was created (format: 
MMMDDDDD YYYYYYYM) 
$1E-$1F The minute (byte $1E) and hour (byte $1F) at which this 
directory entry was created. 
$20 The version number of ProDOS that created this directory. 
$21 The lowest version of ProDOS that is capable of using this 
directory. 
$22 Access code for this directory (see Figure 5-1) 
$23 The number of bytes occupied by each directory entry (39). 
$24 The number of directory entries that can be stored on each 
block (13). 
$25-—$26 The number of active files in this directory (not including 
the directory header) 
$27—-$28 VOLUME DIRECTORY: The block where the volume bit 


map is located (6) SUBDIRECTORY: the block in which 
the entry defining this subdirectory is located (this is in 
the parent directory of the subdirectory). 


$29-$2A VOLUME DIRECTORY: The size of the volume in blocks 
(280). 
$29 SUBDIRECTORY: The directory entry number within the 
block given by $27/$28 that defines this subdirectory (1 to 
13). 
$2A SUBDIRECTORY: The number of bytes in each directory 


entry of the parent directory (39). 
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All directory entries that do not represent directory headers represent either 
standard data files (for example, binary files, text files, and Applesoft pro- 
grams) or subdirectory files. The formats of the directory entries for both of 
these two types of files are virtually identical and are as shown in Table 5-5. 


Table 5-5. Map of a ProDOS directory file entry. 


Relative 
Byte Number Meaning of Entry 
$00 High four bits: storage type (see text) 
— $00 for an inactive file 
—$@1 for a seedling file 
— $02 for a sapling file 
—$03 for a tree file —$QD fora subdirectory file 
Low four bits : length of file name 
$01-SOF File name (in ASCII with bit 7 = 0) 
$10 File type code (see Table 5-6) 
$11-$12 Key pointer. If a subdirectory, the block number of the key 
block of the subdirectory. If a standard file, the block num- 
ber of the index block of the file (or the data block if this 
is a seedling file). 
$13-$14 Size of the file in blocks. 
$15—-$17 Size of the file in bytes (low-order bytes first). 
$18—$19 The date on which this file was created (format: 
MMMDDDDD YYYYYYYM). 
$1A-—$1B The minute (byte $1A) and hour (byte $1B) at which this 
file was created. 
$1C The version number of ProDOS that created this file. 
$1D The lowest version of ProDOS that is capable of using this 
file. 
$1E Access code for this file (see Figure 5-1). 
$1F-$20 For a binary file, the load address of the file; for a random- 
access text file, its record length. 
$21~—$22 The date on which this file was last modified (format: 
MMMDDDDD YYYYYYYM). 
$23—$24 The minute (byte $23) and hour (byte $24) at which this 
hile was created. 
$25-$26 The block number of the key block of the directory that 


holds this file entry. 
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The only way to determine what type of file a particular file entry corre- 
sponds to is to examine the file type code that appears at relative position 
$10 within the entry. Although 256 different codes are possible, only a few 
are commonly used by ProDOS, and it is these that are shown in Table 5-6. 
The three-character mnemonics used to represent these file types in a CAT- 
ALOG listing are also shown in Table 5-6. For a list of all ProDOS file types, 
even the obscure ones, refer to the ProDOS Technical Reference Manual. 


Table 5-6. ProDOS file type codes. 


File Type CATALOG 

Code Mnemonic Type of File 

$04 TXT ASCII text file (with bit 7 = 0) 
$06 BIN Binary file 

$OF DIR Directory file 

$19 ADB AppleWorks database file 

$1A AWP AppleWorks word processing file 
$1B ASP AppleWorks spreadsheet file 
SEF PAS Pascal file 

$FO CMD ProDOS added command file 
$FA INT Integer BASIC program file 
$FB IVR Integer BASIC variable file 
$FC BAS Applesoft program file 

$FD VAR Applesoft variable file 

$FE REL EDASM relocatable code file 
$FF SYS ProDOS system file 


‘Protecting’ Files 


ProDOS allow files to be protected using the LOCK command. If a file is 
locked, then it cannot be altered or renamed unless it is first unlocked. If a 
file is locked, then an asterisk will appear at the far left of the line in which 
the file name appears when the directory is catalogued. 


ProDOS reserves a one-byte access code in its directory entries to indicate 
the write status of the file (at relative byte $1E in each directory entry). Four 
bits in this byte are used to individually control the read, write, rename, and 
delete status of the file. A fifth bit acts as a flag to indicate whether the file 
has been modified since the last time it was backed up (it is the backup 
program's responsibility to clear this bit to @ when the file is backed up). 
These bits are described in Figure 5-1. 


Unfortunately, there is no ProDOS command that can be used from Apple- 
soft to adjust these bits individually. The LOCK command turns off the write, 
rename, and delete bits together and the UNLOCK command turns them all 
back on again. The bits can be changed, however, by directly reading the 
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«— DELETE (1=enabled) 

«— RENAME ~ (1=enabled) 

<«— BACKUP (1=make a backup) 
<«— (RESERVED) 

<—— (RESERVED) 

<«— (RESERVED) 


<— WRITE/SAVE _(1=enabled) 
0! <— READ/LOAD _(1=enabled) 


Figure 5-1. ProDOS access codes bit map. 


block that contains the directory entry, changing the access code, and then 
writing the block back to diskette. The READ.BLOCK program listed in Table 
5-9 will allow you to do this (this program will be described later on). 


Storing File Data 


The method ProDOS uses to keep track of where a standard file’s data is 
stored on the diskette varies depending on the size of the file. ProDOS uses 
the following ““woodsy”’ file classifications: 


Seedling file : 1 to 512 bytes (1 block or less) 
Sapling file : 513 to 131,072 (128K) bytes 
Tree file : 131,073 (128K + 1) to 16,777,215 (16M-1) bytes 


ProDOS determines what type of file it is dealing with by examining the 
four highest bits of relative byte $00 in the directory entry for the file: the 
number stored here is 1 for a seedling file, 2 for a sapling file, and 3 for a tree 


hile. 


ProDOS uses these three different file structures to reduce the amount of 
space needed to manage a file on the diskette to the absolute minimum. This 
permits ProDOS to deal with a file as quickly as possible and frees up valuable 
disk space for the storage of other files. 


The directory entry's key pointer (relative bytes $11 and $12) points to the 
key block on the diskette for the file. Let’s take a look at how ProDOS interprets 
this key block for each of the three types of files. 


Seedling File. A seedling file, which, by definition, cannot exceed 512 
bytes in length, obviously uses only one block on the diskette for data storage. 
It is this block that is pointed to by the key pointer. This means that the key 
block is, in fact, also the sole data block for the file. 
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Sapling File. The key pointer in the directory entry for this type of file 
points to an index block that contains an ordered list of the block numbers 
on the diskette that are used to store that file’s data. Table 5-7 shows what an 
index block for a sapling file looks like. Since block numbers can exceed 255, 
two bytes are needed to store each block number. The low part of the block 
number is always stored in the first half of the block and the high part is 
stored 256 bytes further into the block. The maximum size of a sapling file is 
128K; it cannot be larger than this since only 256 blocks (of 512 bytes each) 
can be pointed to by the index block. 


Table 5-7. Map of the ProDOS index block for a sapling file. 


Byte Number Meaning 

$000 Block number of Oth data block (low) 
$001 Block number of Ist data block (low) 
$002 Block number of 2nd data block (low) 
$QFF Block number of 255th data block (low) 
$100 Block number of Oth data block (high) 
$101 Block number of Ist data block (high) 
$102 Block number of 2nd data block (high) 
$1FF Block number of 255th data block (high) 


Tree File. If the file is a tree file, then the key pointer points to a master 
index block that contains an ordered list of the block numbers of up to 128 
sapling-file-type index blocks. The structure of a master index block is shown 
in Table 5-8. Just as for sapling files, each of the index blocks pointed to by 
the master index block contains an ordered list of block numbers on the 
diskette that the file uses to store its data. The maximum size of a tree file is 
16 megabytes (less one byte, which is reserved for an end-of-file marker)! 


ProDOS takes care of all conversions that might become necessary if a file 
changes its type because it has either grown or shrunk. All this happens 
invisibly and it is not necessary to know what type of file is being dealt unless 
special programs are being used that do not use the standard ProDOS com- 
mands to access files. 


MLI—Accessing the Diskette Directly 


ProDOS supports a special machine-language interface (MLI) protocol that 
makes it extremely simple for assembly-language programs to perform stan- 
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Table 5-8. Map of the ProDOS master index block for a tree file. 


Byte Number Meaning 
$000 Block number of @th index block (low) 
$001 Block number of Ist index block (low) 
$002 Block number of 2nd index block (low) 
$07F Block number of 127th index block (low) 
$100 Block number of Oth index block (high) 
$101 Block number of Ist index block (high) 
$102 Block number of 2nd index block (high) 
$17F Block number of 127th data block (high) 


dard diskette I/O commands. The MLI is explained in detail in Chapter 4 of 
Apple’s ProDOS Technical Reference Manual. 


The same general type of subroutine is used to invoke all MLI commands. 
The code used to invoke an MLI command looks like this (to review, ‘“‘DFB”’ 
is a Merlin Pro assembler directive that causes the byte specified in the 
operand to be stored in memory): 


JSR $BFO@ Call the MLI 

DFB CMDNUM > and execute this command # 
DFB #<CMDLIST ;sLow part of address 

DFB #>CMDLIST ;High part of address 

BCS ERROR ;Error if carry flag set 


where $BF0Q0 is the entry point to the MLI, CMDNUM is the command number 
that ProDOS has assigned to the requested command, and CMDLIST is the 
address of the parameter list associated with the command. (Recall from 
Chapter 2 that if you are using the Apple 6502 Assembler/Editor rather than 
Merlin Pro, then you should replace “#>" with “#<” and vice versa in the 
above example.) The parameter list contains the values of variables that the 
command needs in order to execute properly; result codes are also stored in 
the parameter list. 


After the command is executed, control passes to the code that begins 
immediately after the three bytes stored after the “JSR $BFQQ” instruction. 
If an error occurs, then the carry flag is set, the zero flag is cleared and the 
error code number is placed in the accumulator. You can transfer control to 
an error-handling subroutine by using a BCS instruction (as shown in the 
example) or a BNE instruction. 
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There are two MLI commands that can be used to read from and write to 
individual blocks on the diskette directly. The command numbers for these 
commands are $80 (READ_BLOCK) and $81 (WRITE_BLOCK). The parameter 
lists for these commands are identical and are constructed as follows: 


Ist byte: number of parameters (always $03) 

2nd byte: disk drive to be accessed 

3rd byte: 512-byte data buffer address (low part) 
4th byte: 512-byte data buffer address (high part) 
5th byte: block number to be accessed (low part) 
6th byte: block number to be accessed (high part) 


The second byte in the parameter list contains information relating to the 
location of the diskette to be accessed. The number stored here is $6@ for the 
internal disk drive or $E@ for the external disk drive. 


For example, if a diskette is in the external disk drive and you want to read 
the contents of block number 260 on that diskette into a buffer beginning at 
location $2000, you would use a program that looks like this: 


JSR $BFOG 

DFB $88 ;(Code for READ) 
DFB #<CMDLIST 

DFB #>CMDLIST 

BCS IOQERROR 


°-CGot it!) 
RTS 
IOERROR ‘ ;CDidn’t get it!) 
RTS 
CMDLIST DFB $83 
DFB $E@ sExternal Drive 
DFB $90 ;Buffer address $2000 
DFB $290 
DFB $64 sBlock 260 (€$80104) 
DFB $61 


The same program can be used to write a block to the diskette simply by 
changing the command code from $89 to $81. 


READ.BLOCK Program 


Table 5-9 shows an extremely useful program called READ.BLOCK that 
can be used to examine any of the 280 blocks of data on a ProDOS diskette, 
to edit the contents of a block, and to write a modified block back to the 
diskette. READ.BLOCK makes use of the MLI READ_BLOCK and 
WRITE_BLOCK commands. 


With READ.BLOCK, you can easily look at real examples of the types of 
blocks we have been discussing in this chapter, for example, the volume bit 
map, the directory blocks, the index blocks, and a file’s data blocks themselves. 
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Table 5-9. READ.BLOCK—a program to read any block on a 
ProDOS diskette. 


9 REM "READ.BLOCK" 

188 FOR I = 768 TO 892: READ X: 
POKE 1,X: NEXT 

119 DEF FN MDCX) = X - 16 * INT 


CX / 16) 

120 DEF FN M2CX)d = X - 256 * INT 
CX / 256) 

138 D$ = CHR$ €4) 

148 BM = 279: REM NUMBER OF BLOC 
KS 


1580 TEXT : PRINT CHR$ C21): HOME 
PRINT TABC 16)3;: INVERSE 
PRINT "READ BLOCK": NORMAL 
>: PRINT TABC 11)93;"CC) 1984 
GARY LITTLE" 

168 VTAB 18: CALL - 958: PRINT 
"ENTER BASE BLOCK NUMBER (@- 
";BM;: INPUT "J: “s;T$: IF T$ 

= ""' THEN 168 


178 BL = INT € VAL CT$)): IF BL 
= @ AND T$ < > "@" THEN 16 
g 
180 IF BL <«< @ OR BL > BM THEN 1 
69 


190 RW = 128 
2908 POKE 782, FN Me2CBL): REM BL 
OCK# CLOW) 
218 POKE 783, INT CBL / 256): REM 
BLOCK# CHIGH) 
220 POKE 771,RW: REM READ=128 / 
WRITE=129 
2306 CALL 768 
240 IF PEEK €8) < > @ THEN PRINT 
INVERSE : PRINT “DISK I/O © 
ERROR": NORMAL : PRINT "PRES 
S ANY KEY TQ CONTINUE: “3: GET 
A$: PRINT A$: GOTO 158 
1008 VTAB 4: CALL - 958: PRINT 
TABC 11)9;"CONTENTS OF BLOCK 
*";BL: PRINT : POKE 34,5 
@Qs= 1 
@ HOME : GOSUB 2000: CALL 79 
4:Q@ = @ + 1: IF Q@ = S THEN 1 
950 
1930 IF PR = ®@ THEN GET A$: IF 
A$ = CHR$ €27) THEN 1059 


N = 


(continued) 
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Table 5-9. READ.BLOCK—a program to read any block on a 
ProDOS diskette (continued). 


1049 GOTO 1020 

1050 @ = Q@- 1:PR = @: PRINT D$; 
“PR#O":B = g 

1060 HTAB 1: VTAB 23: CALL - 9 
S8: PRINT "ENTER COMMAND CB, 


C,D,E,N,P,Q,W,HELP): “3s: GET 
A$: IF A$ = CHRE$ €13) THEN 
Ag = "ou 


1878 PRINT A$ 
18080 IF A$ < > "DD" THEN 1118 
18698 @ = @- i: IF Q@ = 9 THEN Q = 


4 

11880 HOME : GOSUB 2008: CALL 79 
4: GOTO 1960 

1110 IF A$ = "H" THEN 5800 

1120 IF A$ = "Q" THEN 1268 

1130 IF A$ = "“E" THEN 1278 

1140 IF AS = "P" THEN 1220 

115@ IF A$ = “"N* THEN 1248 

1168 IF A$ = “BY THEN 158 

1170 IF A$ = "C* THEN VTAB 23: 


CALL - 958: PRINT TABC 6) 


;: INVERSE : PRINT “TURN ON 
PRINTER IN SLOT #1": NORMAL 
:PR = 1: PRINT D$;"PR#1": PRINT 
: GOTO 1990 

1188 IF A$ « > “W' THEN 1218 

119@ POKE 782,BL: POKE 771,129: 
VTAB 23: CALL - 958: PRINT 
"PRESS “’Y’% TO VERIFY WRITE: 


"™s: GET A$: IF A$ = CHRS C1 
3) THEN AS =" ™ 
12080 PRINT A$: IF A$ = “"Y" THEN 


CALL 768:RW = 128: VTAB 23: 
CALL - 958: PRINT "WRITE C 
OMPLETED. PRESS ANY KEY: “3: 
GET A$: GOTO 1068 
1219 GOTO 58088 
1220 BL = BL - 1: IF BL = - 1 THEN 
BL = 279 
1238 GOTO 199 
12490 BL = BL + 1: IF BL > 279 THEN 
BL = 9 
12580 GOTO 198 
1268 TEXT : HOME END 


(continued) 
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Table 5-9. READ.BLOCK—a program to read any block on a 
ProDOS diskette (continued). 


1278 V = 8:H 


TABC 6); 


= 3: VTAB S: PRINT 
: INVERSE : PRINT " 


T=UP M=DOWN J=LEFT K=RIGHT": 


NORMAL 


1280 HTAB 1: 


VTAB 23: CALL - Q 


S58: PRINT TABC 6);"PRESS "3 


INVERSE 


PRINT “ESCs: NORMAL 


PRINT " TO LEAVE EDITOR" 


99 REM 


12 

1360 GOSUB 1500: GET A$ 

131@ LO = 16384 + 128 * (Q - 1) + 
8 *« V + H:Y = PEEK CLCOC):X = 


ASC CA$) 


1320 IF A$ 


CHR$ €27) THEN HTAB 


1: VTAB 5S: CALL - 868: GOTO 


1068 


1330 IF A$ < 


1349 B= @:V 


®@ THEN 1300 
1358 V = 15:Q@ = 


1360 


1370 IF A$ 


1380 IF A$ 


1390 IF A$ < 


1400 B= @:V 


> "I" THEN 1379 
= V- 1: IF Vd = 


Q- 1: IF @ << 1 THEN 


Q 

GOSUB 29800: HOME CALL 79 
4: GOTO 1288 
H 
7 


"J" THEN B = @:H = 


- 1: IF H = - 1 THEN H = 
“K* THEN B = @:H = 
H + 1: IF H = 8 THEN H = @ 
> "mM" THEN 1438 
= V+ 1: IF V <«< 16 THEN 
= @+ 1: IF @ = S THEN 


1428 GOTO 1368 


1430 IF B= 
> + 16 * 
57) + 16 
65) 

1440 IF B= 
CY / 16) 
57) + CX 


®@ THEN Y = FN MDCY 
CX - 48) * CX «€ = 
* €X - $5) * CX > = 


1 THEN Y = 16 * INT 
+ €X - 48) * CX <€ = 
- 55) * (X > = 65) 


14580 X = ASC CAS): IF CX > = 4 


8 AND X < 


65 AND X 


= 57) OR CX > = 
< = 70) THEN PRINT 


A$;: POKE € PEEK (48) + 256 * 


(continued) 
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Table 5-9. READ.BLOCK—a program to read any block on a 
ProDOS diskette (continued). 


PEEK €41) + 31 + H),Y: POKE 
LC,Y: IF B = @ THEN CALL 64 
50@:B = 1 

1468 IF X = 8 AND B = 1 THEN B = 
0 


1478 IF X = 21 AND B = @ THEN B 
= 1 
1488 GOTO 1389 


14998 CALL - 167 
15800 VTAB V + 6: HTAB 3 * H + 7 
+ B: RETURN 


CO88 IF Q@ = 1 THEN POKE 795,8: 
POKE 799,64 
2019 IF Q@ = 2 THEN POKE 795,12 
8: POKE 799,64 
2920 IF Q@ = 3 THEN POKE 795,8: 
POKE 799,65 
28030 IF Q@ = 4 THEN POKE 795,12 
8: POKE 799,65 
2048 RETURN 
5808 HOME : PRINT TABC 10)3;"SU 
MMARY OF COMMANDS": PRINT TABC 
19); Sts=sssseseeeeesressest!, PRINT 
S5891@ PRINT "“B--RESET BASE BLO 
CK! 


58920 PRINT “C--COPY BLOCK CON 
TENTS TO PRINTER" 

9838 PRINT “D--DISPLAY PREVIO 
US 1/4 BLOCK" 

5048 PRINT “E--EDIT THE CURRE 


NT BLOCK" 

5858 PRINT “N--READ THE NEXT 
BLOCK" 

5868 PRINT “P--READ THE PREVI 
OUS BLOCK" 


5870 PRINT “G--QUIT THE PROGR 


S5@8@ PRINT “W--WRITE THE BLOC 
K TO DISK* 

5898 PRINT : PRINT “PRESS ANY K 
EY TO CONTINUE: “3: GET A$: PRINT 
A$: GOTO 1188 

8880 DATA 32,9,191,128,10,3,144 
»8,176,11,3,96,8,64,8,8,169, 
0@,133,8,96,169,1,133,8,96,16 
9,8,133,6 


(continued) 
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Table 5-9. READ.BLOCK—a program to read any block ona 
ProDOS diskette (continued). 


8819 DATA 169,64,133,7,162,8,16 
@,09,56,165,7,233,64,32,218,2 
53,165,6,32,218,253,169,186, 
32 ,237,253,169,168 ,32,237 

8820 DATA 253,177,6,32,218,253, 
169,160 ,32,237,253,209 ,192,8 
,208 ,241 ,169,160,32,237,253, 
168,9,177,6,9,18,201 ,160,17 


6 
8030 DATA 2,169,174,32,237,253, 
200,192,8,2908,238,169,141,32 
,237,253,24,165,6,185,8,133, 
6,165,7,1905,909,133,7,232 
8848 DATA 224,16,298,168,96 


You should be careful when writing a block to a diskette, however, as it is 
easy to accidentally render the diskette unreadable; you should always exper- 
iment on a backup copy of the original diskette. 


When READ.BLOCK is first run, you will be asked to enter a base block 
number. After this information has been provided, the block corresponding 
to that location on the diskette will be read into memory and displayed on 
the screen in a special format. Because of 40-column screen size limitations, 
only one-quarter of the block can be represented at once (you have to press 
the “‘D” key to display the other quarters). 


The contents of a block are displayed in 64 rows, each of which contains an 
offset address from the beginning of a block followed by the hexadecimal 
representations of the eight bytes stored from that location onward in the 
block. At the far right of each row are the ASCII representations of each of 
these eight bytes. Note that only 16 rows are displayed at any one time. 


After the entire block has been displayed, you will be asked to enter one of 
eight commands. The meanings of each of these commands are as follows: 


‘“B’’—reset the base block 

‘“‘C’’—copy the contents of the block to the printer (in port 1) 
“D"—display the next quarter of the current block 
“E’’—edit the current block 

‘“‘N’’—read and display the next block on the diskette 
‘“P’’—read and display the previous block on the diskette 
“Q”"—quit the program 

“W’’—write the block back onto the diskette 


The functions that most of these commands perform are obvious. The only 
‘tricky’ one is the ‘E”’ (Edit) command. When the Edit command is entered, 
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the cursor will move into the middle of the 8x16 array of hexadecimal digits 
that represent the contents of one-quarter of the block. To change any of these 
digits, use the I, J, K, and M keys to move the cursor up, left, right, and down, 
respectively, and then enter the new two-digit hexadecimal entry for that 
position. You can leave editing mode at any time by pressing the ESC key. 
Once you have left editing mode, you can save the changes to diskette by 
using the ‘“W”’ (Write) command. 
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Character Input and the 
Keyboard 


The //c, like most other microcomputers, usually deals with information 
that is delivered to it in one-byte (8-bit) chunks (from a keyboard or a disk 
drive, for example). This information is commonly referred to as ‘‘character’’ 
input because the bytes usually represent the encoded representations of 
letters of the alphabet, numbers, and other printable characters. Although 
any encoding scheme that the input device cares to use could be dealt with 
by the //c, it is the American National Standard Code for Information Inter- 
change (ASCII) standard that is usually used to encode characters. Two other 
incompatible encoding schemes, Extended Binary-Coded Decimal Inter- 
change Code (EBCDIC) and Baudot, are also in widespread use, the first by 
all large IBM computers (except the IBM PC series) and compatibles and the 
second by some older TeleType terminals. 


ASCII is a seven-bit code and is used by virtually all microcomputers. A 
total of 128 (2“7) codes are defined by the ASCII standard and each code fits 
nicely into one byte with one bit (bit 7) to spare. Table 6-1 contains a list of 
these codes, their standard names or symbols, and the keys on the keyboard 
(or combination of keys) that must be pressed to enter them. 


When the //c performs character input/output operations, the ASCII code 
for the character is stored in bits @ through 6 of the byte being inputted or 
outputted and bit 7 of the byte is normally set equal to “1”. Since a “1” in bit 
7 is often used to indicate that the value stored in that byte is negative, this 
“variant” of ASCII is called “negative ASCII”; if bit 7 is @, then “positive 
ASCII” is being used. 


Note that all but the first 32 ASCII codes and ASCII code 127 (rubout) are 
used to represent visible symbols. The first 32 codes are called “control 
characters” and are usually sent to a video display or printer controller to 
cause it to perform some special action. Some of the more important control 
characters on the //c are as follows (in negative ASCH): 
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Table 6-1. American National Standard Code for Information 
Interchange (ASCID character codes. 


ASCII 
Code 
Hex Dec Symbol 


$00 
$01 
$02 
$03 
$04 
$05 
$06 
$07 
$08 


$09 
$0A 


$0B 
$0C 
$0D 
$OE 
$OF 
$10 
$11 
$12 
$13 
$14 
$15 


$16 
$17 


$18 
$19 
$1A 
$1B 
$1C 
$1D 
$1E 
$1F 
$20 
$21 
$22 
$23 
$24 
$25 
$26 


000 
001 
002 
003 
004 
005 
006 
007 
008 


009 
010 


Oil 
@12 
013 
014 
015 
016 
017 
018 
019 
020 
Q21 


022 
023 


024 
025 
026 
027 
028 
029 
030 
031 
032 
033 
034 
035 
036 
037 
038 


NUL 
SOH 
STX 
ETX 
EOT 
ENQ 
ACK 
BEL 
BS 


HT 
LF 


VT 
FF 
CR 
SO 
SI 
DLE 
DC1 
DC2 
DC3 
DC4 
NAK 


SYN 
ETB 


CAN 
EM 
SUB 
ESC 
FS 


(Null) 

(Start of header) 
(Start of text) 

(End of text) 

(End of transmission) 
(Enquiry) 
(Acknowledge) 

(Bell) 

(Backspace) 


(Horizontal tabulation) 
(Line feed) 


(Vertical tabulation) 
(Form feed) 
(Carriage return) 
(Shift out) 

(Shift in) 

(Data link escape) 
(Device control 1) 
(Device control 2) 
(Device control 3) 
(Device control 4) 
(Negative acknowledge) 


(Synchronous idle) 


(End of transmission block) 


CONTROL W 
(Cancel) 

(End of medium) 
(Substitute) 
(Escape) 

(Field separator) 
(Group separator) 
(Record separator) 
(Unit separator) 
(Space) 


Keys to Press 


CONTROL @ 
CONTROLA 
CONTROL B 
CONTROL C 
CONTROL D 
CONTROL E 
CONTROL F 
CONTROL G 
LEFT-ARROW or 
CONTROL H 

TAB or CONTROL I 
DOWN-ARROW or 
CONTROL J 
UP-ARROW or CONTROL K 
CONTROL L 
RETURN or CONTROL M 
CONTROL N 
CONTROL O 
CONTROL P 
CONTROL Q 
CONTROL R 
CONTROLS 
CONTROL T 
RIGHT-ARROW or 
CONTROL U 
CONTROL V 


CONTROL X 
CONTROL Y 
CONTROL Z 
ESC or CONTROL [ 
CONTROL \ 
CONTROL | 
CONTROL * 
CONTROL _ 
SPACE BAR 
SHIFT 1 
SHIFT ” 
SHIFT 3 
SHIFT 4 
SHIFT 5 
SHIFT 7 
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Table 6-1. American National Standard Code for Information 
Interchange (ASCII) character codes (continued). 


ASCII 

Code 
Hex Dec Symbol Keys to Press 
$27 039 ' 
$28 040 ( SHIFT 9 
$29 @41 ) SHIFT 0 
$2A 042 * SHIFT 8 
$2B 043 + SHIFT = 
$2C 044 
$2D 045 
$2E 046 . 
$2F 047 / / 
$30 048 © 0 
$31 049 1 1 
$32 050 2 2 
$33 051 3 3 
$34 052 4 4 
$35 053 5 5 
$36 054 6 6 
$37 055 7 7 
$38 056 8 8 
$39 057 9 9 
$3A 058 SHIFT ; 
$3B 59 ; 
$3C 060 < SHIFT , 
$3D @61 = = 
$3E 062 > SHIFT . 
$3F 063 ? SHIFT / 
$40 064 @ SHIFT 2 
$41 065 A SHIFT A 
$42 066 B SHIFT B 
$43 067 C SHIFT C 
$44 068 D SHIFT D 
$45 069 E SHIFT E 
$46 070 F SHIFT F 
$47 071 G SHIFT G 
$48 072 H SHIFT H 
$49 073 I SHIFT I 
$4A 074 J SHIFT J 
$4B 075 K SHIFT K 
$4C 076 L SHIFT L 
$4D 077 M SHIFT M 
$4E 078 N SHIFT N 
$4F 079 O SHIFT O 
$50 080 P SHIFT P 
$51 081 Q SHIFT Q 
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Table 6-1. American National Standard Code for Information 
Interchange (ASCII) character codes (continued). 


ASCII 
Code 
Hex Dec 


$52 082 
$53 083 
$54 084 
$55 085 
$56 086 
$57 087 
$58 088 
$59 089 
$5A 090 
$5B 091 
$5C 092 
$5D 093 
$5E 094 
$5F 095 SHIFT - 
$60 096 
$61 097 
$62 098 
$63 099 
$64 100 
$65 101 
$66 102 
$67 103 
$68 104 
$69 105 
$6A 106 
$6B 107 
$6C 108 
$6D 109 
$6E 110 
$6F 111 
$70 112 
$71 113 
$72 114 
$73 115 
$74 116 
$75 117 
$76 118 
$77 119 
$78 120 
$79 121 
$7A 122 
$7B 123 { SHIFT [ 
$7C 124 | SHIFT \ 


< 
3 
oe 
S 


Keys to Press 


SHIFT R 
SHIFT S 
SHIFT T 
SHIFT U 
SHIFT V 
SHIFT W 
SHIFT X 
SHIFT Y 
SHIFT Z 


SH -ONK MSS CHORD 


Nx x Ecce TMBtOvos gs THT ho AO Tw 


NX xX S<CHODOVOZZOCAGTOMNMOO 
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Table 6-1. American National Standard Code for Information 
Interchange (ASCII) character codes (continued). 


ASCII 

Code 
Hex Dec Symbol Keys to Press 
$7D 125 } SHIFT ] 
$7E 126 ~ SHIFT ‘ 
$7F 127 @ (Rubout) DELETE 


$87 (bell)—-causes the speaker to beep 

$88 (backspace)—causes the cursor to move back one position 

$8A (line feed)—causes the cursor to move down one line 

$8D (carriage return)—causes the cursor to move to the beginning of the 
current line 


Some of the names associated with the control characters (see Table 6-1) 
are somewhat archaic in that they refer to various aspects of the operation of 
old TeleType terminals. Other names relate to the codes used by certain 
standard data-interchange protocols that are used in telecommunications 
networks (for example, Start of Text (STX), End of Text (ETX), and Cancel 
(CAN)). 


In this chapter, we will take a look at how the //c requests and reads 
character input from any device interfaced to it, including the keyboard. In 
doing so, we will examine the built-in ROM subroutines that the //c normally 
uses whenever it requires character input. 


You will be able to follow this chapter a lot more easily if you have by your 
side a copy of the source code listings for the Apple //c monitor ROM. They 
can be found in “The Apple //c Reference Manual”, volume 2. 


Standard Character Input Subroutines 


There are three special, general-purpose character input subroutines in the 
//c’s system monitor that are used to fetch characters so that they can be used 
and interpreted by other parts of the system, including Applesoft and the 
system monitor. These routines are usually referred to by the symbolic names 
of RDKEY, RDCHAR, and GETLN. (A fourth subroutine, ESCRDKEY, is 
functionally identical to RDCHAR.) They, in turn, usually make use of two 
other subroutines that are used to read information from the keyboard; these 
are called KEYIN and C3KEYIN. Each of these subroutines are briefly described 
in Table 6-2. Let’s take a closer look at them. 
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Table 6-2. Built-in input subroutines. 


Address 
Hex (Dec) Symbolic Name Description 

$FDOC (64780) RDKEY Reads a character from the currently 
active input device and places its neg- 
ative ASCII code in the accumulator. 

$FD35 (64821) RDCHAR Both use RDKEY to read a character 

$CCED (52461) ESCRDKEY from the currently active input device 
and both enable escape sequences. 

$FD1B (64795) KEYIN Keyboard input routine used when 80- 


column firmware is not being used. 
The negative ASCII code for the char- 
acter is returned in the accumulator. 


$C305 (51446) C3KEYIN Keyboard input routine used when 80- 
column firmware is being used. The 
negative ASCII code for the character 
is returned in the accumulator. 


$FD6A (64874) GETLN Reads a line of information into the 
input buffer at $200 by making 
repeated calls to ESCRDKEY. 


Reading One Character 


RDKEY ($FDQC) 


Because RDKEY is the fundamental character input subroutine that is 
eventually called by the other two, it is the most important of the three. This 
subroutine is used to scan any input device that has been designated as being 
active (usually, but not necessarily, the keyboard) until a character has been 
entered, and to return the ASCII code for that character (with its high bit set 


to one) in the 65C@2’s accumulator. The Applesoft GET command calls RDKEY 
directly. 


As soon as RDKEY is called, it loads the character stored at the currently 
active video position (as calculated from the values of CH ($24) and CV ($25), 
the horizontal and vertical cursor coordinates). The code that does this looks 
like this: 


LDY CH sGet horizontal position 
LDA CBASL),Y ;Get the screen byte 
NOP 


sCSeven more NOPs) 
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where BASL ($28) is the first of two zero page locations that together contain 
the base address for the line number held in CV. (See Chapter 7.) 


After the screen character has been obtained, the following code is executed: 
JMP CKSWL) 


which effectively passes control to the body of a user-selectable input subrou- 
tine whose address is held at KSWL ($38) and KSWH ($39). This input 
subroutine is responsible for returning the ASCII code for an inputted char- 
acter as soon as the input device being used makes one available. For the 
purposes of this discussion, we will assume that the input device is the //c’s 
keyboard. We will see later on how other input devices can be linked into the 
RDKEY subroutine instead by simply storing the address of the input sub- 
routine for the alternative input device at KSWL and KSWH. 


The //c’s ProDOS disk operating system is integrated into the system by 
storing the address of its special input subroutine at KSWL and KSWH. This 
input subroutine will read input from either a diskette file or the keyboard, 
depending on whether or not a ProDOS READ command is in effect. It will 
also cause special disk operations to be performed if a valid ProDOS command 
is entered from the keyboard (for example, LOAD a file and CATALOG the 
diskette). When it reads information from the keyboard, it uses one of the 
//c’s two built-in subroutines available for this purpose. 


The keyboard input subroutine that is used will depend on whether the //c’s 
internal 80-column firmware ROM is being used. This firmware is not on 
when you first turn on the //c but can be selected by entering a PR#3 command 
from Applesoft. Once you have selected the 80-column firmware in this way, 
you can flip between an 80-column display and a 40-column display by using 
the two-keystroke “escape sequence’’ 


ESC 4 
to go from 8@-column mode to 40-column mode and 
ESC 8 


to go from 4@-column mode to 8@-column mode. (An escape sequence is 
entered by pressing the ESC key, releasing it, and then pressing the second 
key; the [return] key must not be pressed.) 


You can usually tell whether the 80-column firmware is being used by 
looking at the cursor. If it’s a blinking “checkerboard,” then the 80-column 
firmware is not in use; if it’s a nonflashing, inverse-video square, then it is. 
The 80-column firmware can be deactivated by entering an ESC [control-Q] 
sequence from the keyboard or printing a [control-U] character; either method 
returns you to standard 4@-column mode. (You can also use the PR#0 com- 
mand to return to standard 40-column mode, but only if ProDOS is not being 
used. This method will not work at all on the Apple //e, however.) 


We will be looking at the video display modes in considerably more detail 
in Chapter 7. 
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Keyboard Input 


If the 80-column firmware on the //c is not being used, then the //c usually 
uses a subroutine called KEYIN ($FD1B) to handle keyboard input. If the 80- 
column firmware is active, then the C3KEYIN ($C305) subroutine is used 
instead. C3KEYIN, however, simply calls the KEYIN subroutine to handle 
keyboard input. KEYIN behaves slightly differently for each video mode, 
however; it determines which mode is active by examining the contents of 
certain memory locations that are set up when the video modes are initialized. 


The first thing that KEYIN does is to set up a cursor on the screen by calling 
SHOWCUR ($CC4C). SHOWCUR examines location CURSOR ($7FB) to deter- 
mine what type of cursor to set up. If the number stored there is $FF, then a 
“checkerboard” cursor will be displayed; this is the cursor that is normally 
used when the standard 4@-column display is active. If the number stored at 
CURSOR is @, then the cursor used is an inverse block; this is the one that is 
normally used when the 80-column firmware is active. If you store any other 
number at CURSOR, you can generate all sorts of interesting blinking cursors. 
For example, by storing 186 at CURSOR, the cursor will be a blinking colon. 


The blinking cursors used by the //c are generated by using software timing 
loops. For example, to display the checkerboard cursor, the //c alternates 
between the display of the checkerboard character (ASCII code $FF) and the 
true screen character at fixed intervals. 


When a key that generates an ASCII code is entered, the cursor is removed 
by placing the screen character back on the screen, and then the ASCII code 
representing the entered key is placed in the 65C@2’s accumulator (with the 
high bit set to one). 


At this point, KEYIN moves on to the GOTKEY ($FD25) subroutine. This 
subroutine examines bit 3 of location VMODE ($4FB), the escape enable bit, 
to determine whether it should just pass the keyboard character along to the 
caller or whether to process it further. 


If bit 3 of VMODE is 0, then KEYIN ends with the character code still in 
the accumulator. If it is 1, however, then GOTKEY checks to see if the char- 
acter that was entered was the ESC key. If it wasn't, then the escape enable 
bit of VMODE is turned off and KEYIN ends. 


Escape Sequences 


If, however, the ESC key is pressed, then KEYIN does something quite 
different: control passes to NEWESC ($CCCC), which causes the cursor to 
change to an inverse ‘+’ sign and ‘‘escape mode” to be turned on. Whenever 
the //c is in this mode, it reads the keyboard once again and then executes a 
special function dictated by the key that is read. This two-key combination 
is commonly referred to as an “escape sequence.” A list of all of the valid 
escape sequences and the functions they perform are listed in Table 6-3. 
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Table 6-3. Escape sequences. 


Escape 
Sequence Description 

ESC @ Clears the video screen window and places the cursor 
in the top left-hand corner. 

ESCA Moves the cursor one position to the right. 

ESC B Moves the cursor one position to the left. 

ESC C Moves the cursor down one line. 

ESC D Moves the cursor up one line (if not already at top). 

ESC E Clears the screen from the current cursor position to 
the end of the line. The cursor position does not change. 

ESC F Clears the screen from the current cursor position to 
the end of the window. The cursor position does not 
change. 

ESC I Moves the cursor up one line and keeps escape mode 

ESC f active. 

ESC J Moves the cursor one position to the left and keeps 

ESC <— escape mode active. 

ESC K Moves the cursor one position to the right and keeps 

ESC > escape mode active. 

ESC M Moves the cursor down one line and keeps escape mode 

ESC | active. 

ESC 4 Switches to 40-column mode from 80-column mode. 

ESC 8 Switches to 80-column mode from 40-column mode. 


ESC [control-Q] 


ESC [control-D] 


ESC [control-E] 


Deselects the 80-column firmware and returns to stan- 
dard 40-column mode. 


Disables the printing of control characters when the 
80-column firmware is active (other than carriage return, 
line feed, backspace, and bell). 


Enables the printing of all control characters. 


Most of the escape sequences that have been defined on the //c are used to 
move the cursor around the screen or to affect the video display in some way 
and are adequately explained in Table 6-3. Two of them are somewhat unusual: 
they are ESC [control-D] and ESC [control-E]. 


ESC [control-D] is used to disable any special interpretation of control 
characters that are sent to the standard output subroutine other than the 
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codes for carriage return ($8D), line feed ($8A), backspace ($88), and bell ($87). 
As we will see in Chapter 7, the //c reacts in special ways to several other 
control characters that are sent to its output subroutine when the 80-column 
firmware is being used. For example, if a [control-U] character is printed, you 
can move from the 80-column display to a 40-column display. This is a handy 
way of exiting 80-column mode, but what if you happen to be communicating 
with a remote computer through the modem port when you receive a [control- 
U] character that the computer uses to indicate that a file is ready to be 
transferred? Before you know it, you will pop out of 80-column mode and you 
will be left scratching your head wondering what happened. To avoid this 
type of trouble it is best to enter the ESC [control-D] sequence before running 
such a program. You can re-enable the handling of the control codes later by 
entering the ESC [control-E] sequence. 


In general, escape mode ends immediately after the key after ESC has been 
pressed and, if you want to re-enter escape mode, you must press ESC once 
again. The I,J,K,M and arrow-key sequences, however, behave somewhat 
differently. If you enter any of these sequences, then escape mode remains 
active until any other key that generates an ASCII code that is not part of an 
escape sequence is pressed. This means that you can quickly move the cursor 
around the screen by pressing ESC once and then pressing any sequence of 
cursor-movement keys until the cursor is properly positioned. You can then 
press another key (the space bar is convenient) to leave escape mode. 


When escape mode ends, the keyboard character that was last pressed is 
returned in the accumulator and KEYIN ends. 


RDCHAR ($FD35) and ESCRDKEY ($CCED) 


The RDCHAR and ESCRDKEY subroutines simply turn on the escape 
enable bit in VMODE ($4FB) before jumping to the start of the RDKEY 
subroutine to get input. This tells the RDKEY subroutine to handle any escape 
sequences that may be entered before a standard character code is returned. 


The RDCHAR subroutine is actually identical to the ESCRDKEY subrou- 
tine since it simply jumps to the start of ESCRDKEY as soon as it is called. 
It has been made available for the sake of compatibility with the earlier Apple 
II models which had a similar subroutine located at $FD35. 


Reading a Line of Characters 


RDKEY, RDCHAR, and ESCRDKEY read only one character at a time. A 
much more useful and general subroutine is one that allows you to enter a 
whole line of information at once (a line being defined as a series of characters 


that is entered before [return] is pressed). Such a subroutine does exist on the 
//c and is called GETLN ($FD6A). 
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The GETLN subroutine is used by the //c whenever you are entering com- 
mands in the system monitor or in Applesoft direct mode. In addition, the 
Applesoft INPUT command uses this subroutine directly. 


As soon as GETLN is called, a special symbol, called a prompt symbol, is 
displayed. The code for this symbol is always read from PROMPT ($33). This 
symbol serves two purposes: it tells you what part of the //c is currently active 
(the system monitor or Applesoft, for example) and it reminds you that the 
//c is expecting you to enter a line of information. Table 6-4 sets out the various 
prompts symbols commonly used by the //c. 


Table 6-4. //c prompt symbols. 


Prompt Symbol Meaning 


* the system monitor is waiting for a command. 


J Applesoft is waiting for you to enter a command ora 
program line. 

? Applesoft is waiting for you to respond to an INPUT 
statement. 


Note: The ASCII code for the prompt symbol is kept in PROMPT ($33). 


After the prompt symbol has been displayed, GETLN calls ESCRDKEY 
again and again until the [return] key is pressed. The characters returned by 
the series of RDCHAR calls are stored in consecutive locations in a 256-byte 
character input buffer located in page two of memory beginning at IN ($200). 
When [return] is pressed, the subroutine ends and the number of characters 
in the buffer is returned in the X register. 


When a line is entered using GETLN, all those escape sequences that are 
normally available can be used. In addition, GETLN supports several simple 
editing commands that can be used when the line is being entered. These 
editing commands will now be discussed. 


Left-Arrow Key. This key allows you to backspace over the previous item 
in the input buffer and, thus, to remove it from the buffer. The cursor moves 
one position to the left on the video screen when the left-arrow key is pressed. 


Right-Arrow Key. This key allows you to copy the character on the video 
screen beneath the cursor into the input buffer. 


Ctrl-X. This key allows you to erase everything that is currently in the 
input buffer. When it is pressed, a backslash (‘‘V’) will be displayed after the 
characters that have already been typed in and the cursor will be placed at 
the far left of the next line on the screen. Note that the line will automatically 
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be canceled like this if you attempt to enter more than 255 characters before 
pressing [return]. Beeps will be sounded after every character entered after 
the 248th one to remind you that the buffer is almost full. 


Return. This key indicates to GETLN that the current line is completed 
and is to be entered. 


Changing Input Devices: The Input Link 


The most common source of character input to the //c is the keyboard. It is 
possible, however, to redirect it to other input devices which can be connected 
to the //c through its built-in expansion ports. A familiar example of such a 
source is the //c’s disk drive. 


The //c uses a very flexible method for handling the problems associated 
with having many possible sources of character input. Even though the source 
of the input may vary, calls are still always made to the RDKEY subroutine 
whenever a character from any device, in general, is required. To activate a 
particular device, the destination of a jump instruction that RDKEY uses to 
locate the character input subroutine is set to the address of the device’s input 
subroutine. This means that your program's input commands (for example, 
INPUT and GET in Applesoft) can always be used regardless of the source of 
input. 


Let’s take a closer look at the mechanics of this procedure. We saw earlier 
that whenever RDKEY is called to obtain another character, control ulti- 
mately passes to an instruction that looks like this: 


JMP €$0038) 


The addressing mode used by the jump instruction here is called “indirect.” 
This means that the destination of the jump is not location $38 itself but 
rather the address stored at locations $38 (low byte) and $39 (high byte). This 
address is normally a subroutine within ProDOS that ultimately calls KEYIN 
($FD1B) or C3KEYIN ($C305), the system monitor’s standard keyboard input 
routines (unless input is being requested from a diskette file). By simply 
changing the address stored at $38/$39, however, you can force the //c to 
execute any subroutine that you want whenever input is requested, including 
one associated with an alternative input device. 


The symbolic name for locations $38/$39 is KSW (for keyboard switch); 
$38 by itself is called KSWL and $39 is called KSWH. Since these locations 
are used to incorporate new input routines into the system, KSW is commonly 
referred to as the “input link’ or “input hook.” 


The address of the input subroutine for a peripheral input device is usually 
placed in KSWL and KSWH by using the Applesoft “IN#s” command. This 
command causes the //c to transfer control to a program beginning at location 
$Cs0O0 (where “‘s” is a valid port number) that is the first location in a ROM 
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area reserved for that port. The program in the ROM area will modify KSW 
so that it will point to a new input routine also contained in that ROM. Note 
that if an IN#@ command is entered, then the address of KEYIN ($FD1B), the 
//c’s standard 4@-column input subroutine, will be stored at KSWL and KSWH. 


You can also change the input hook by using the Applesoft POKE command 
to store the address of the new input routine directly into KSW at $38 and 
$39; this address can be in a ROM area or a RAM area. 


How About Output? 


You may well be wondering whether the //c uses the same method to handle 
its output that it uses to handle its input. The answer is, you guessed it, ‘‘yes,’’ 
but we re going to defer discussion of output until Chapter 7. For those of you 
who just can't wait, the //c uses an output link called CSW ($36/$37) to point 
to the output subroutine that is to take control whenever the standard output 
subroutine, COUT ($FDED), is called. The PR# command can be used to 
transfer control to a port in much the same way that IN¥ can be. 


Designing a KSW Input Subroutine 


A KSW input subroutine must be designed carefully to ensure that it adheres 
to certain rules that restrict its usage of 65C@2 registers. The most important 
rule is that when the subroutine ends, the inputted character must be con- 
tained in the accumulator with its high-order bit set to one. Furthermore, the 
X and Y registers must contain the same values they held when the subroutine 
was first entered. Thus, if X and Y are to be changed by the KSW subroutine, 
they must first be saved in a safe place (such as the stack) and then restored 
just before the subroutine ends. 


Replacing the Keyboard Input Subroutine 


As we Saw earlier, the //c comes with a built-in keyboard input subroutine 
called KEYIN ($FD1B). This subroutine takes care of setting up the cursor 
and of scanning the keyboard until a key has been pressed. There is nothing 
magic about this particular subroutine, however, and you could easily replace 
it with another program that would still get input from the keyboard, but 
would do it differently. In fact, this is essentially what is done whenever you 
enter a PR#3 command to turn on the //c’s 80-column display. As we have 
seen, when this is done, RDKEY uses a new keyboard input routine called 
C3KEYIN which changes the type of cursor that is used. 


You can use your own imagination to dream up some useful features that 
could be added to a keyboard input subroutine. Some interesting ones to 
think about are as follows: 
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® The ability to prevent certain characters from being entered. 


@ Allowing additional escape sequences. 


@ Allowing for macro keys. (A macro key is one that, when pressed, causes 
a whole string of characters to be entered.) 


Later in this chapter, after we have seen how to read the keyboard, we will 
present some examples of modifying the keyboard input subroutine to meet 
special requirements such as these. 


It is fairly simple to redefine the keyboard input subroutine so that it 
operates properly in whatever video mode is currently active. In fact, only 
five basic steps need be performed: 


@ Set up a cursor. 

@ Wait for a key to be pressed (while blinking the cursor, if desired). 
@ Remove the cursor. 

@ Handle escape sequences (if desired). 


@ Return with the key code in the accumulator. 


The //c’s KEYIN ($FD1B) subroutine is, of course, the perfect example of a 
KSW subroutine that performs these five steps when it is called. We looked 
at how KEYIN works earlier in this chapter, but let’s quickly relate its activ- 
ities to each of the five steps. 


KEYIN first sets up a cursor (step 1) by calling SHOWCUR ($CC4C) to 
display the character stored at CURSOR ($7FB) at the currently active cursor 
position. It then repeatedly calls the UPDATE ($CC790) subroutine until a key 
has been pressed (step 2). The UPDATE subroutine takes care of blinking the 
cursor at the proper rate (if necessary) and will remove the cursor after a key 
is pressed by calling STORY ($C3B3) with the original screen character in 
the accumulator (step 3). After a key has been pressed, KEYIN calls the 
GOTKEY ($FD25) subroutine to handle any valid escape sequences that may 
be entered (step 4). Finally, KEYIN ends with the ASCII code for the keyboard 
character in the accumulator with its high bit set to 1 (step 5). 


The basic subroutines used by KEYIN to perform its duties are summarized 
in Table 6-5. These are built-in to the //c’s ROM and may be used by your own 
programs, if desired. 


ProDOS and the Input Link 


The ability to change the KSW input link is somewhat restricted if ProDOS 
is active. (Similar restrictions apply if the CSW output link is to be changed.) 
When ProDOS is first activated, the address stored in the KSW input link is 
placed in another input link located within ProDOS itself. A special KSW 
input subroutine is then installed that is responsible for detecting and exe- 
cuting any ProDOS commands that are entered (when Applesoft direct mode 
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Table 6-5. Built-In subroutines used by KEYIN ($FD1B). 


Address 


Hex 


(Dec) 


$CC4C (52300) 


$CC70 


$C3B3 


$FD25 


(52336) 


(50099) 


(64805) 


Symbolic Name 
SHOWCUR 


UPDATE 


STORY 


GOTKEY 


Description 


Displays the character stored at CUR- 
SOR ($7FB) at the current cursor posi- 
tion and designates it as the active cur- 
sor. 


Causes the cursor to blink at the proper 
rate (if non-zero) and scans the key- 
board for input. Ifa key is pressed, then 
the N-flag in the processor status reg- 
ister is set to 1, the character code is 
placed in the accumulator, and the cur- 
sor is removed by calling STORY 
($C3B3) to restore the original screen 
character. If a key is not pressed, then 
the N-flag is set to @. 


Stores the byte in the accumulator on 
the video screen at the current cursor 
position. 


If escape sequences are enabled, checks 
to see if ESC was pressed; if it was, then 
the keyboard is read again and any valid 
escape sequence is executed. Escape 
sequences are enabled if input is 
requested by the Applesoft INPUT 
command or the monitor's GETLN 
($FD35) subroutine. They are not 
enabled by the Applesoft GET com- 
mand. 


is active) and for redirecting the source of input to a diskette file if a ProDOS 
READ command is in effect. Ifa READ command is not in effect, then ProDOS 
uses the subroutine whose address is stored in its own input link to get input. 
The address stored here is initially that of one of the standard keyboard input 
subroutines. 


If standard attempts are made to modify KSW, then ProDOS could be 
temporarily disconnected. With one exception, this means that you must not 
use any of the following methods to install a new input subroutine: 


@ Using an Applesoft “IN#s” command (as opposed to the ProDOS PRINT 
CHR$(4);“IN#s’ command) from within a program. 


@ Using Applesoft POKE commands to place new values directly into KSWL 
and KSWH. 
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@ Using the Applesoft CALL command or the system monitor GO command 
(as opposed to the ProoDOS BRUN command) to execute an assembly- 
language program that stores values directly into KSWL and KSWH. 


The exception relates to the use of the BRUN command. If an assembly- 
language program is loaded and executed directly from diskette by using the 
BRUN command, then the program is permitted to modify the contents of 
KSW and both ProDOS and the new input subroutine will still remain active. 
This is because just before the program that is BRUN ends, ProDOS checks 
to see whether the input link has changed. If it has, it moves the link address 
into its own input link and places the address of its input subroutine back 
into KSW. 


You can also successfully store a new input subroutine by storing its address 
directly into the ProDOS input links found at $BE32 and $BE33 instead of 
into KSW. 


If you want to use an IN¥ command within an Applesoft program in order 
to redirect input to a particular port, you must use the ProDOS “version” of 
that command by printing a [control-D] character (ASCII code 4), immedi- 
ately followed by “IN#s”’ (where ‘‘s”’ is the port number) and a carriage return. 
The [control-D] signifies to ProDOS that a ProDOS command is about to be 
presented; it can be generated using the Applesoft CHR$ function. For exam- 
ple, to redirect input to serial port 2 when ProDOS is being used, execute the 
following statement from within a program: 


PRINT CHRS$C4);"IN#¥2" 


instead of the Applesoft ‘‘IN#2” command. After this is done, both ProDOS 
and the new input subroutine will be active. 


ProDOS supports a special form of the IN# command that its predecessor, 
DOS 3.3, does not. This special IN# command can be used to properly install 
an input subroutine that is located anywhere in memory and not just to pass 
control to a program located at a port. The only restriction on its use is that 
the first byte of the new input subroutine must be a 65C@2 “CLD” (clear 
decimal flag) instruction. To install any such input subroutine, you must 
execute the statement 


PRINT CHRSC4);"IN# Aaddr™ 


where “addr” represents either the decimal starting address of the new input 
subroutine or, if preceded by “$’’, the hexadecimal starting address. For 
example, if your new input subroutine begins at $300 (decimal 768), then you 
would execute either of the following two statements: 

PRINT CHR$C4);"IN# AS3GB" 


or 


PRINT CHRS$C4);""IN# A768" 
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and the new input subroutine will be properly installed in the ProDOS input 
link. 


The Keyboard 


The keyboard is one of the most important input/output device attached to 
the //c. It is one of two primary sources of input (the disk drive being the other 
one) and without it you would not be able to interact conveniently with any 
program running on the //c. 


We are now going to take a close look at the keyboard. We will explain how 
it is used to enter information and present examples of how to modify the 
handling of keyboard input to meet special requirements. 


Encoding of Keyboard Characters 


The //c’s keyboard is made up of 62 typewriter-like keys that include most 
of the ones that you would see on a standard typewriter as well as a few more 
special ones. The keycaps are spatially arranged in the standard QWERTY 
(Sholes) configuration that is familiar to all typists. You should note, however, 
that as far as the //c is concerned, the mapping of keys to characters is not 
dictated by the keycaps, but rather by the setting of the ‘‘keyboard” switch 
which is found just above the keyboard to the right of the “reset” button and 
the “80/40” switch. 


With the keyboard switch in its normal position (up), a QWERTY (Sholes) 
mapping scheme is used and the keycap does, indeed, indicate the character 
that is entered when a key is pressed. However, if the keyboard switch is 
down, then the keys are mapped to the Dvorak keyboard configuration shown 
in Figure 6-1. The characters on the Dvorak keyboard are arranged in such a 
way as to permit a typist to maximize typing speed. This is possible because 
the more frequently used letters are placed on the home row (where the fingers 
of a touch typist normally sit) so that they can be located and struck more 
rapidly than if they were located elsewhere. Conversely, the Sholes keyboard 
arrangement was designed to minimize typing speed so that the striking 
hammers in the original mechanical typewriters would not become tangled. 


All of the keys on the keyboard except for the two ‘“‘Apple’’ keys that flank 
the space bar, are used to generate the ASCII codes that the //c uses to represent 
the 52 alphabetic characters (26 uppercase and 26 lowercase), 10 digits (0. . . 9), 
34 special symbols, and 32 “control’’ codes that it recognizes. 


Some keys on the keyboard do not generate ASCII codes when pressed by 
themselves, but are used to affect the code that is normally generated by 
another key that is pressed at the same time. These keys are the two SHIFT 
keys, the CONTROL key, and the CAPS LOCK key. 
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Figure 6-1. The Sholes and Dvorak keyboard layouts. 


You can probably guess how the SHIFT keys affect the character codes 
already. Ignoring the effect of the CAPS LOCK key for the moment, if you 
press any alphabetic key by itself, you will generate an ASCII code for a 
lowercase character. If either SHIFT key is pressed at the same time, however, 
the ASCII code for the corresponding uppercase character is generated instead. 
The SHIFT key is also pressed to select the ASCII code for the top symbol on 
those keys that have two symbols marked on them. 


The CAPS LOCK key, if in the down position, merely causes any lowercase 
alphabetic character code that is entered to be converted to the code for the 
corresponding uppercase character. 


The CONTROL key acts in a similar way as the SHIFT keys. If you hold the 
CONTROL key down and then press any of the 26 alphabetic keys, then an 
ASCII code for a control character will be selected and not the code for the 
alphabetic key itself. (The remaining six control characters are generated by 
pressing the CONTROL key together with one of the following special sym- 
bols: @, [,\, ], *, and _). 


6 / Character Input and the Keyboard [| 159 
special Keys 


There are several special keys on the //c's keyboard that you probably won’t 
see on a standard typewriter. These are the ESC (for ESCape), TAB, DELETE, 
UP-ARROW, DOWN-ARROW, LEFT-ARROW, RIGHT-ARROW, OPEN-APPLE, 
and SOLID-APPLE keys as well as the CONTROL key that was discussed 
above. 


The ESC, TAB, DELETE, and the four arrow keys all generate specific ASCII 
codes when they are pressed and they are often referred to as “editing” keys. 
Refer to Table 6-1 for the ASCII codes generated by these keys. 


Different programs will perform different tasks when an editing key is 
pressed. It is hoped, however, that the tasks performed will relate in a mean- 
ingful way to the name or the symbol on the keycap. That is, it would be 
preferable if the ESC key actually caused you to ESCape (or exit) some part 
of a program and the TAB key caused the cursor to move several spaces to 
the right, and so on. It would be incredibly annoying, for example, if when 
you pressed the down-arrow key your cursor moved up or if you pressed the 
DELETE and the cursor moved five spaces to the right. 


The “‘Apple’’ Keys 


The OPEN-APPLE and SOLID-APPLE keys that flank the space bar are 
actually equivalent to push buttons #0 and #1, respectively, on a joystick or 
a pair of game controllers that are interfaced to the mouse/game connector 
at the back of the //c. These push buttons will be described in detail in Chapter 
10. Although these keys cannot be used to generate ASCII codes, they could 
be used, with appropriate software, to act as special shift keys. The software, 
after reading a key, could check to see whether an “Apple” key was being 
pressed; if one was, then a different action could be taken than if the key were 
pressed by itself. For example, Apple has issued design guidelines urging 
software developers to consider the question mark key as a “HELP” key if it 
is pressed at the same time as the OPEN-APPLE key. Here is how you would 
implement a help function in an Applesoft program: 


18 PRINT “Enter a command: ‘s;:GET A$ 
28 IF AS="?"" AND PEEKC49249)9127 THEN 1000 


1000 REM PLACE “HELP” CODE HERE 


Memory location 49249 is the address of the location that holds the state 
of the OPEN-APPLE key. (49250 is used for the SOLID-APPLE key.) If the 
value read from this location is greater than 127 (that is, bit 7 is on), then 
OPEN-APPLE is being pressed. 


The OPEN-APPLE key can also be used to modify the effect of resetting the 
//c. This is discussed in the last section of this chapter. 
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Keyboard I/O Locations 


The Apple //c reserves two I/O memory locations for use by the keyboard 
I/O device. These two locations are $C000 and $C@10 and their meanings are 
summarized in Table 6-6. 


Table 6-6. Keyboard I/O locations. 


Address 
Hex (Dec) SymbolicName Meaning 

$C00® (49152) KBD Keyboard data and strobe. Keyboard 
data is stored in bits @... 6. Bit 7 rep- 
resents the keyboard strobe and will 
be 1 if keyboard data is ready to be 

read. 
$C010 (49168) KBDSTRB Clear keyboard strobe and read any- 
or AKD key-down status. Reading or writing 


this location will clear the keyboard 
strobe bit at $C000. Bit 7 indicates 
whether a key is being pressed; if it is 
1, then a key is being pressed. 


KBD ($C@09) is used to hold the 7-bit ASCII code for any keyboard character 
that is entered as well as a 1-bit ‘strobe’ flag. The strobe flag is held in bit 7 
of KBD and indicates whether a key has been pressed and is ready to be 
presented to the system. If the bit is set to 1, then keyboard data is ready to 
be read; if it is cleared to 0, then no keyboard character has yet been entered 
since the last time the strobe was cleared. The lower 7 bits of KBD always 
contains the ASCII code of the last key entered. The keyboard strobe is also 
connected to an input line on the integrated circuit that controls serial port 
2 at the back of the //c; this has been done in such a way that interrupts can 
be generated whenever a key is pressed. We will be looking at these keyboard 
interrupts in Chapter 11. 


The second keyboard I/O location is KBDSTRB ($C@10). This location is 
used for two purposes. First, if any read or write operation is performed on 
this location, such as a PEEK or a POKE, then the keyboard strobe bit (in 
KBD) will be cleared to zero. This tells the //c’s built-in keyboard input 
subroutines that the keyboard data has already been dealt with and that no 
further information should be read from the keyboard until the strobe flag 
becomes set once again. 
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Second, bit 7 of KBDSTRB ($C@10), also called AKD ($C@10), indicates the 
status of the ‘“‘any-key-down’”’ flag. If it is 1, then a key is being pressed; if it 
is @, then no key is being pressed. This flag is not the same as the strobe flag 
because, as we will see later on, there are times when even though a key is 
being pressed, it has not yet been “‘officially” strobed into the system. 


Here is a simple assembly-language program to read data from the key- 


board: 


WAITFORKEY LDA $C699 ;Get keyboard data + strobe 
BPL WAITFORKEY ;Loop until strobe is set 
STA $C818 ;Clear keyboard strobe 


The branch-on-plus (BPL) instruction will cause this program to loop until 


KBD becomes “negative,” that is, until bit 7 of KBD (the strobe bit) becomes 
1. 


In Applesoft, this program would be written as follows: 


100 IF PEEKC491S52)<128 THEN 108 : REM WAIT FOR STROBE 
118 POKE 49168,8 : REM CLEAR KEYBOARD STROBE 


It is important that the keyboard strobe be cleared after reading data from 
the keyboard. If it isn’t, the program will keep thinking that a key has just 
been pressed whenever it checks for more keyboard data. 


Let’s look at a simple program, called TYPING.TIMER, that makes use of 
the AKD ($C010) flag; it is shown in Table 6-7. This program analyzes your 
typing speed by displaying the length of time your finger stays on each key 
that you press and the time delay between successive keystrokes. It does this 
by simply monitoring the status of the AKD flag and keeping track of the 
elapsed time using a software counter. In a fully developed program of this 
sort, you would be able to quickly pinpoint a typist’s problem areas. 


After you enter the program, you can run it by entering CALL 768 from 
Applesoft direct mode. After you do this, type in four characters from the 
keyboard as fast as you can. After you have done this, a set of six times (in 
units of 20 microseconds) will be displayed. The meanings of each of these 
times are as follows: 


First :ON time for first key 

Second :delay between first and second keys 
Third :ON time for second key 

Fourth  :delay between second and third keys 
Fifth :ON time for third key 

Sixth :delay between third and fourth keys 


To convert the displayed numbers into milliseconds, simply divide them 
by fifty. You should take note of how the decimal values for these times are 
displayed. The program makes use of an Applesoft subroutine called LINPRT 
($ED24); this subroutine takes a binary number that is in X (low byte) and A 
(high byte) and displays it as an unsigned decimal number. 
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Modifying the Keyboard Input Subroutine 


Earlier in this chapter, we saw how it was possible to replace the subroutine 
that the //c uses in order to obtain character input by simply changing the 
input link at KSW ($38/$39). At that time, we indicated that it would be 
possible to install a wide variety of subroutines that would still obtain input 
from the keyboard but would do it in different, more useful, ways. 


Look at the program called MACRO.ENTRY in Table 6-8. It must be installed 
by using the BRUN command to execute it directly from diskette. This pro- 
gram allows you to automatically enter a commonly used command phrase 
from the keyboard simply by pressing the OPEN-APPLE key at the same time 
as one of three other keys, C, H, or L. These keys will generate the following 
sequences of characters: 


C — CATALOG,D1 (followed by [return]) 
H — HOME (followed by [return]) 
L — LOAD (followed by [space]) 


A key that is used to enter a whole string of other characters is called a 
macro key. With MACRO.ENTRY installed, it is a simple matter to catalog 
the disk, clear the screen, or to “type in’’ LOAD before specifying the name of 
a program. All you must do is press OPEN-APPLE and the appropriate macro 
key. 


The first part of MACRO.ENTRY simply sets up the new input link so that 
it points to NEWIN, the start of the new input routine. This means that every 
time a program requests input from the //c by calling the standard RDKEY 
($FDOC) input subroutine, control will eventually pass to NEWIN instead of 
the standard keyboard input subroutine. 


When NEWIN is entered, some registers that will be used are first saved 
and then a location (called MACROFLG) is checked to see whether a 
macro entry is currently being processed. If not, the program enters a 
tight loop until a keypress is detected. After a key has been pressed, the 
character is loaded into the accumulator and the status of the OPEN-APPLE 
key is examined with a BIT OPENAPL instruction. If it is not being pressed, 
then the following BPL instruction will succeed (because bit 7 of OPENAPL 
will be 0) and control will return to the calling program as usual. 


However, if OPEN-APPLE is being pressed, then the MACROKEY table is 
scanned to see whether it contains the keyboard character that has been 
entered. If it doesn't, then control returns to the calling program. If it does, 
then the high-order bit of MACROFLG is set and the first character of the 
entry in the PHRASES table is returned to the calling program. Each time 
that input is requested after this, the next character in the macro phrase will 
be returned to the calling program. This will continue until all characters 
have been returned, at which time MACROFLG is cleared. 
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If you want to change the macro commands and associated entries, then 
you must modify the MACROKEY and PHRASES tables. The ASCII code for 
each command key must be stored in the MACROKEY table with the high 
bit on. The corresponding macro phrases for each key must be stored, in 
order, in the PHRASES table; each phrase must be terminated by a 00 byte. 
In addition, you must set MTOTAL equal to the number of macro keys in the 
MACROKEY table before reassembling the program. 


Recall that only locations $300 through $3CF are available for use in page 
three of memory. You must ensure that your macro tables are short enough 
that you do not spill over the $3CF boundary. 


Keyboard Auto-Repeat 


When you enter a key that corresponds to a particular ASCII code, that 
code will begin to repeat after you have kept the key pressed for longer than 
about 900 milliseconds. (This time could be shorter, but heavy-handed typists 
might then encounter difficulties.) Once this ‘‘pre-repeat”’ period has elapsed, 
the code will begin to repeat itself 15 times per second (that is, once every 
66.7 milliseconds). The auto-repeat phenomenon is generated by circuitry on 
the //c’s motherboard. 


The auto-repeat feature is useful if you are editing programs or if are you 
are using word-processing programs. In both cases, it is often necessary to 
repeat character sequences or use an arrow key several times in succession 
to move the cursor to a new position. These tasks can be done easily merely 
by pressing the appropriate key and holding it down until the key is repeated 
as many times as is required. 


The timing diagram for the keyboard’s auto-repeat function is shown in 
Figure 6-2. As soon as a key is first pressed, the AKD ($C@10) flag is turned on 
and, a few microseconds later, the keyboard strobe is turned on. The keyboard 
strobe will then stay on until it is cleared by accessing KBDSTRB ($C010). 
This is done right after the keyboard is read by the standard keyboard input 
subroutines. Note, however, that if the key is still being pressed, the AKD flag 
will remain on even after the strobe has been cleared. 


After the strobe is cleared, and if the key is still being pressed, there is a 
short delay of about 900 milliseconds (called the ‘‘pre-repeat’’ delay) and then 
the keyboard strobe is turned on again. As usual, it will stay on until KBDSTRB 
is accessed once again. The width of the strobe pulse will depend on how 
rapidly the strobe is cleared after the strobe is turned on. Figure 6-2 was 
prepared by assuming that this is happening soon after the strobe is high and 
certainly much faster than the rate at which the key repeats. 


At this stage, the keyboard strobe will automatically be turned on once 
every 66.7 milliseconds after it has been cleared and until the key is finally 
released. Even while the keyboard strobe is being turned on and off, however, 
the AKD flag remains on; in fact, AKD is turned off only when the key is 
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PRE-REPEAT PERIOD REPEAT PERIOD 

+200 msec. “66.7 msec. 

a b c d 

| KEYBOARD STROBE 


SIGNAL ($C0@@) 


ANY-KEY-DOWN 


SIGNAL ($C010) 


ON 


OFF 


ON 


OFF 


t KEY FIRST PRESSED tKEY RELEASED 


NOTE: The keyboard strobe is cleared at 
points “a”, “b’, “c”, and “d” by 
accessing KBDSTRB ($C@1@). 


Figure 6-2. Keyboard auto-repeat timing diagram. 


finally released. Thus, there are substantial periods of time when even though 
the AKD flag is on (that is, a key is being pressed), the keyboard strobe is not 
on. 


Since most keyboard input subroutines, including the standard ones used 
in the //c, rely on the keyboard strobe to detect the presence or absence of a 
valid key code, the key code will be repeated at the same rate that the strobe 
is turned on (this is fixed by the //c’s internal circuitry). If, however, an 
alternative input subroutine is used that examines the AKD flag and returns 
a key code if it is on continuously for a given time period (even though, at the 
end of the period, the keyboard strobe may not be on), then a different repeat 
rate can be generated in software. 


The AUTO.REPEAT program in Table 6-9 shows you how to adjust the auto- 
repeat rate in software. This program must be installed by using the BRUN 
command to load and execute it directly from diskette. AUTO.REPEAT mod- 
ifies the input link so that it points to the code beginning at NEWIN. After 
this has been done, all requests for keyboard input will be processed by this 
subroutine and a much faster auto-repeat rate will be observed. 


The first thing the new input subroutine does when it is called is to deter- 
mine whether a new character was entered the last time it was called (RPTFLAG 
= $00) or whether an old one was being repeated (RPTFLAG = $80). Ifa new 
character was entered, then the accumulator is loaded with the number given 
by PREDELAY (the pre-repeat delay time); if not, it is loaded with the smaller 
number given by RPTDELAY (the auto-repeat time interval). 
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A delay loop is then entered during which the status of the AKD flag is 
repeatedly checked. If the flag is turned off (that is, the key is released) at any 
time before the loop finishes, then RPTFLAG is set equal to $00 (to indicate 
that repeating has ended) and then keyboard input is requested in the stan- 
dard way (by waiting for the keyboard strobe to be turned on). After a key- 
board character is received, it is stored in OLDKEY. 


If a key remains pressed until the timing loop finishes, then the keyboard 
data is immediately read from KBD ($C000), even though the strobe may not 
actually be on. This data will usually equal the code stored in OLDKEY (the 
previous key strobed in). If at some time during the loop, however, another 
key was pressed before the previous one was released, it will be different. If 
the key code is the same (the usual case), RPTFLAG is set equal to $80. This 
indicates that an auto-repeat sequence is in effect so that the next time input 
is requested, the shorter ‘‘RPTDELAY” delay loop will be selected. Otherwise, 
RPTFLAG is set to $00. In either case, the key code is stored in OLDKEY 
before the subroutine finishes. 


The important point to note here is that the keyboard data will always be 
read after the key has been pressed for the length of time set by the loop 
counter (PREDELAY or RPTDELAY). Thus, we can select both the auto-repeat 
rate and the predelay time simply by changing the RPTDELAY and PRE- 
DELAY constants. You may want to try out different repeat rates and predelay 
times by changing these constants in the program. Be warned, however, that 
if you set RPTDELAY too low, your reflexes may not be fast enough to control 
the speeding cursor! You should also be careful not to set PREDELAY too low 
or else you may not be able to press and release a key before it starts to repeat! 


Resetting the Apple //c 


The RESET button is located above the upper left-hand corner of the 
keyboard just above the ESC key. It should really be called a “panic” button 
since it is usually used to interrupt the running of a program when all else 
fails. After a reset signal is generated by pressing the RESET button, the //c 
generally returns to Applesoft direct mode from where you can easily examine 
the program that was just running or you can load and run another one. 


Actually, the RESET button does nothing really important if you press it 
by itself. If you press it while you are also holding down the CONTROL key, 
however, then the reset pin on the 65C@2 microprocessor will be held in a low 
state, causing the 65CQ2 to begin its standard reset procedure. This procedure 
was described in Chapter 2. 


Special RESET Procedure 


If the OPEN-APPLE key is held down when [control-RESET] is pressed, 
then a ‘“‘cold” reset procedure will begin that always allows you to restart the 
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/ic. This means that the diskette in the //c’s built-in disk drive will start to 
boot up just as it did when the power was first turned on. This reset procedure 
cannot be prevented and will destroy any program that may be in memory 
when it is requested. 


Trapping “Soft” RESETs 


The reset procedure just mentioned cannot be avoided using software tech- 
niques because it is wholly contained within the //c’s ROM. It is possible, 
however, to redirect a standard “soft” reset (invoked by pressing [control- 
RESET] by itself) to any routine that you want to use to trap such a condition. 


When [control-RESET]’is pressed, the 65C@2 microprocessor jumps to a 
location stored at locations $FFFC/$FFFD (low byte first). On the //c, these 
locations are stored either in the system monitor ROM area or in the bank- 
switched RAM area that shares the same address space as the system monitor, 
depending on which one was enabled when the reset signal occurred. (See 
Chapter 8 for a discussion of bank-switched RAM.) The ROM locations always 
hold the address of RESET ($FA62) in the system monitor but any address 
can be stored in bank-switched RAM. If ProDOS is being used, the address 
stored is $FFCB, which is the start of a ProDOS subroutine that re-enables 
the system monitor ROM and then passes control to the standard reset handler 
at RESET ($FA62). 


The subroutine that begins at $FA62 takes care of some general-purpose 
housekeeping chores (like setting normal video, selecting the keyboard and 
video screen for I/O, and so on), checks for the special OPEN-APPLE reset, 
and then, if the special reset has not been requested, checks to see whether a 
user-defined reset handling routine should be executed. 


If the result of the logical exclusive-OR of the value stored at SOFTEVH 
($3F3) with the constant $A5 is stored at PWREDUP ($3F4), the //c will jump 
to a subroutine whose address is tained in SOFTEV ($3F2/$3F3) (low-order 
byte first). If this test fails, then the the diskette in the disk drive will be 
rebooted. The important reset locations are summarized in Table 6-10. 


Thus, to trap a RESET condition, two things must be done: 
@ The address of the subroutine that is to take control after a reset must 
be stored at SOFTEV. 


@ The byte stored at $3F3 must be logically exclusive-ORed with $A5, and 
the result stored at $3F4. This can be done by executing the following 
instructions: 


LDA $3F3 
EOR #$AS 
STA $3F4 


Right after the //c is turned on, SOFTEV is initialized to $E000, the cold 
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Table 6-10. Reset interrupt locations. 


Address Description 
Hex (Dec) Symbolic Name 


$FFFC (65532) RESETV (low) Reset vector. These locations con- 


$FFFD (65533) (high) tain the address of the subroutine 
that is called when a reset signal 
occurs. 

$03F2 (1010) SOFTEV (low) User-defined reset vector. These 

$03F3 (1011) (high) locations contain the address of a 


user-installed subroutine to which 
control is passed when a reset signal 
occurs (if PWREDUP is set up prop- 
erly). 


$3F4 (1012) PWREDUP Powered-up byte. If the value stored 
here is the same as the result of the 
logical exclusive-OR of the value at 
$3F3 with $A5, then control will pass 
to the user-defined subroutine spec- 
ified by SOFTEV. 


start for Applesoft, and then, after [control-RESET] has been pressed once, 
to $E003, the warm start for Applesoft. If ProDOS is being used, then SOFTEV 
will later be adjusted so that it points to a reset handler within ProDOS itself. 
This handler takes care of reconnecting ProDOS after RESET is pressed and 
of entering Applesoft direct mode. (When RESET is pressed, the addresses of 
the standard keyboard input and output subroutines are stored in the input 
and output links, thus effectively “removing’’ ProDOS from the system.) 


By the way, the reason for storing the ‘‘funny’’ number at PWREDUP is to 
allow the //c to detect whether or not it has just been turned on. If it has been, 
then it is highly unlikely that PWREDUP will be properly ‘‘related’”’ to SOF- 
TEVH, and the //c will interpet this to mean that the diskette must be auto- 
matically booted. 


Trapping RESET from Assembly Language 


If an assembly-language program is being executed, any reset condition 
that may occur can be easily trapped by setting up SOFTEV and PWREDUP 
as indicated above as soon as the program begins. The error-handling routine 
to which SOFTEV points must handle the reset in an orderly manner; its 
main duty will be to ensure that the data areas of the program still make 
sense and to take appropriate action if they do not. For example, if RESET is 
pressed after one byte of a two-byte pointer has been set up, then the reset 


176 {| Inside the Apple //c 


handler had better detect this and fix it or else the next time that the program 
uses this (incomplete) pointer it will disappear into outer space. 


It is also important to ensure that the reset-handling routine adjusts the 
stack pointer to a suitable value. Remember that RESET can be pressed at 
any time, including times when there are several bytes of information stored 
on the stack. If you don't adjust the stack pointer downward in these situa- 
tions, it might eventually “overflow,” allowing you to overwrite important 
information stored on the stack. A simple way of handling this problem is to 
always reset the stack pointer to its value when the program was first entered. 
To do this, execute the following two instructions when beginning your assem- 
bly-language program: 

TSX 

STX STACKSV 


where STACKSV refers to a memory location. In the reset-handling routine, 
the original stack pointer can be restored by executing the following instruc- 
tions: 


LDX STACKSV 
TXS 


and then the remainder of the reset-handling routine can be executed. 


Another important chore for the reset-handling routine to perform is to 
reconnect ProDOS (recall that ProDOS is deactivated whenever the //c is 
reset). This is most easily done by initially saving the ProDOS addresses stored 
in the input and output links (at $36 . . . $39) in safe locations so that the links 
to ProDOS can be restored when RESET is trapped. 


Trapping RESET from Applesoft 


RESET can be trapped while running an Applesoft program by using Apple- 
soft’s built-in error-handling subroutine. If this is done properly, then every 
time the //c is reset, the program can be caused to go to the line number that 
is specified in the currently active ONERR GOTO statement. 


The following steps must be performed by the subroutine that traps reset 
when Applesoft is active: 


@® The ProDOS I/O addresses must be stored in the I/O links to reactivate 
ProDOS. 


@ The value stored at VFACTV ($67B) must be set equal to the value stored 
there before the //c was reset. VFACTV is used as a flag by the video 
firmware to determine whether the 80-column firmware is to be used to 
perform video operations. If VFACTV is greater than 127, then standard 
40-column mode is active; otherwise, the 80-column firmware is active. 


® The 80-column video display must be turned on (but only if it was on 
before the //c was reset). 
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e A subroutine at $D683 must be called to properly configure the 65C@2 
stack. 


@ The program should put an error code number in the X register and then 
execute a ‘“JMP $D412” to pass control to the Applesoft ONERR GOTO 
handler. (The handler will place the error code number in location 222.) 


To install such a subroutine, its starting address must be stored in SOFTEV 
(low-order byte first) and PWREDUP must be properly adjusted as discussed 
above. 


You can reactivate ProDOS using the technique mentioned at the end of 
the last section: save the values of the I/O links when the reset-handling 
subroutine is first installed and then restore them when RESET is pressed. 


When RESET is pressed, the //c automatically turns off the 80-column 
display and a $00 byte is stored at VFACTV ($67B) to indicate that the 80- 
column firmware is not in use. Thus, the reset-trapping subroutine must take 
care of restoring VFACTV to its value just before RESET was pressed and of 
re-enabling the 80-column display, if necessary, by writing to 830COLON 
($COOD). Note, however, that this last step is only to be performed if the 80- 
column display was active when RESET was pressed. The only way for the 
reset handler to determine whether it was is to examine a flag that contains 
the contents of the 80COL ($C01F) status location immediately before the //c 
was reset. This flag can be initialized in the subroutine that sets up the reset 
vector, but it must be updated whenever the display mode is changed. Simi- 
larly, the value of VFACTV must be stored in a safe temporary location so 
that it can be restored properly after RESET has been pressed. 


The subroutine at $D683 must be called in order to fix a bug in Applesoft 
which arises when an error (that is not handled by the Applesoft RESUME 
command) occurs within a FOR/NEXT loop or a GOSUB/RETURN subrou- 
tine. This bug causes incorrect information to be left on the 65C@2 stack after 
the error is processed. 


Applesoft and ProDOS all store error code numbers in location $DE (222) 
whenever an error occurs. The ONERR GOTO error-handling routine can 
then examine this location using a PEEK(222) command to determine what 
kind of error occurred. (See Table 6-12 for a list of Applesoft and ProDOS 
error code numbers.) Several error code numbers are not used by either 
Applesoft or ProDOS, including number 253. Thus, if the X register is loaded 
with 253 just before calling $D412, the Applesoft error-handling subroutine 
will be able to detect a reset ‘error’ by determining whether PEEK(222) = 253. 
PEEK(222) = 253. 


Table 6-11 contains a program that will set up the reset vector so that it 
points to a subroutine that traps reset when an Applesoft program is being 
run. To use it effectively, an ONERR GOTO statement must always be active; 
that is, error-trapping should never be turned off with a POKE 216,0 com- 
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Table 6-12. Applesoft and ProDOS error codes and messages. 


Error Code 


Error Message 


no error occurred [ProDos] or NEXT WITHOUT FOR 
[Applesoft] 

RANGE ERROR 

NO DEVICE CONNECTED 
WRITE PROTECTED 

END OF DATA 

PATH NOT FOUND 

PATH NOT FOUND 

VO ERROR 

DISK FULL 

FILE LOCKED 

INVALID PARAMETER 

NO BUFFERS AVAILABLE 
FILE TYPE MISMATCH 
PROGRAM TOO LARGE 
NOT DIRECT COMMAND 
SYNTAX ERROR 
DIRECTORY FULL 

FILE NOT OPEN 
DUPLICATE FILE NAME 
FILE BUSY 

FILE(S) STILL OPEN 
DIRECT COMMAND [ProDOS] or RETURN WITHOUT 
GOSUB [Applesoft] 

OUT OF DATA 

ILLEGAL QUANTITY 
OVERFLOW 

OUT OF MEMORY 
UNDEFINED STATEMENT 
BAD SUBSCRIPT 
REDIMENSIONED ARRAY 
DIVISION BY ZERO 

TYPE MISMATCH 

STRING TOO LONG 
FORMULA TOO COMPLEX 
UNDEFINED FUNCTION 
BAD RESPONSE TO INPUT STATEMENT 
[control-C] PRESSED 
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mand. The error-trapping subroutine must be installed by loading into mem- 


ory and then executing a CALL 768 command. It must not be BRUN directly 
from diskette. 


Further Reading for Chapter 6 


On changing the input link ... 


G. Little, ““Zoom and Squeeze’, Micro, July 1980, pp. 37-38. This article 
shows how the input link can be changed to control keyboard input. 


On ProDOS and the input link ... 


C. Fretwell, “Setting I/O Hooks in ProDOS”, Call -A.P.P.L.E., April 1984, 
p.39 


On trapping RESET ... 


E.A. Seiden, ‘““ProDOS Reset Trap’, Nibble, October 1984, p.107. This article 
presents an alternative way to trap RESET when ProDOS is active. 


Character and Graphic 
Output and Video Display 
Modes 


In this chapter, we will be discussing the primary output device supported 
by the //c: the video display monitor. This will include an analysis of how 
both text and graphic information are generated and how alternative output 
devices can be easily integrated into the system. 


The //c is capable of controlling the video display in such a way as to support 
three general classes of output modes: 


@ Text mode 
® Low-resolution graphics mode 


@ High-resolution graphics mode 


All of these modes can exist in a standard single-width format or in a special 
double-width format (which includes an 80-column text mode). 


Text mode is used whenever the standard character symbols represented 
by ASCII codes or the special limited graphics character set called MouseText 
are to be displayed on the screen. Both graphics modes are used to illuminate 
distinct blocks (low-resolution graphics) or points (high-resolution graphics) 
on the screen so that a variety of shapes can be generated. Whereas text can 
be displayed in black-and-white only, both graphics modes can be used to 


generate colored images if a color monitor or television set is connected to 
the //c. 


The //c uses a “memory-mapped” video display technique. This means that 
the display of information on the video screen can be controlled simply by 
storing bytes of information in special memory locations that make up part 
of the 65C@2’s 64K address space; these locations are mapped to unique 
positions on the screen display. Similarly, information shown on the video 
screen can be retrieved by reading the contents of these memory locations. 
These memory locations are connected to the //c’s video display support 
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circuitry in such a way that the bytes stored are converted into appropriate 
pictorial representations on the video display monitor. 


Text Mode 


The //c is capable of displaying text in either a 40-column-by-24-row mode 
or a double-width 80-column-by-24-row mode. 


There are actually two versions of 40-column text mode supported by the 
ic. The “standard” 40-column mode is easily identified by its characteristic 
“checkerboard” cursor that is displayed whenever keyboard information is 
being requested. The other version is the “‘special’’ 40-column mode that is 
available when the //c’s 80-column firmware is being used; in this mode the 
cursor is an inverse block that does not flash. 


The 80-column text mode can be invoked in several ways. The most common 
are as follows: 


@ Entering a PR#3 command from Applesoft direct mode 


@ Executing a PRINT CHR$(4);"“PR#3" command from within an Applesoft 
program 


@ Entering the ESC 8 escape sequence whenever the //c is requesting a line 
of information 


All of these commands activate the //c’s special 80-column firmware which 
is capable of displaying information properly on the 80-column text screen. 
This is done by changing the addresses stored in the //c’s input and output 
links and setting various flags in memory locations that are examined by the 
system monitor's subroutines. 


Once you are in 8@-column mode, you can switch between the 80-column 
mode and the special 40-column mode whenever keyboard information is 
being requested by using the two special escape sequences discussed in Chap- 
ter 6: ESC 4 and ESC 8. For example, if you are in 8@-column mode and you 
want to enter the special 40-column mode, enter the sequence 


ESC 4 


If you want to go in the opposite direction, enter the sequence 
ESC 8 


To leave either the special 40-column mode or 80-column mode and go back 
to the standard 40-column mode, you can do one of two things (apart from 
resetting the system). First, you can enter ESC [control-Q] from the keyboard 
or you can print a [control-U] character (by using a PRINT CHR§(21) com- 
mand). 


If you are not using ProDOS, you can also use the PR#0 and IN#0 com- 
mands to reconnect the standard 40-column input and output subroutines, 
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KEYIN ($FD1B) and COUT1 ($FDF@), and to turn off the 80-column screen 
display. ProDOS will ignore these commands, however, for the sake of com- 
patability with the Apple //e. (On the Apple //e, entering PR#@ when the 80- 
column display is enabled will reconnect the standard 40-column I/O links 
alright, but will not turn off the 80-column display. Not a pretty sight!) 


In the following sections, we will be taking a closer look at the memory- 
mapped video RAM areas, the standard character output subroutines that 
are built into the //c, and the soft switches used to select the video display 
mode. 


The 80/40 Switch 


Before we go on, a word about the “80/40” switch that is located just above 
the keyboard to the right of the “reset’’ button. Despite its name, this switch. 
has no effect at all on the video display mode. Its purpose is to indicate to 
any program that is running whether the video display device that is being 
used is capable of displaying 80 columns of text. If you are using a normal 
television set, then it will be nearly impossible to read an 80-column line and 
so this switch should be put in the down (40) position. However, if you are 
using a video monitor, then you can put it in the up (8@) position. 


This method of indicating whether you can support an 80-column screen is 
not foolproof, however. If the program that is running does not check the 
switch, then you may well be treated to an unreadable 80-column display on 
your television set. The only solution is to modify the software so that it takes 
the setting of the switch into consideration. 


The status of the 80/40 switch can be determined by reading a soft switch 
at RD80SW ($C@60). If the number read is greater than 127, then the switch 
is in the 40-column position (down); otherwise it is in the 80-column position. 


Turning on the Text Display 


The //c uses several input/output (I/O) memory locations as soft switches to 
control various aspects of the video display as well as several locations that 
can be read to determine the states of these switches. These locations are 
summarized in Table 7-1 and we will be referring to them throughout this 
chapter. Notice that the soft switches are arranged in pairs of locations, one 
of which turns the switch on and another which turns it off. 


To activate a particular soft switch, other than those from $C@5@ . . . $C@57, 
you must write to its location using an Applesoft POKE command or an 
assembly-language write instruction like STA. You can activate any of the 
switches from $C@50...$CQ57 by either reading or writing. Each pair of on/ 
off soft switches is associated with a status location that can be read to 
determine the state of the switch. The status is kept in bit 7 which means that 
the associated switch will be on if the value read from the status location is 
greater than or equal to 128. 
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The //c uses the TEXT and 80COL switches to select the video display mode 
to be used. The TEXT switches are used to select either a graphics mode or a 
text mode. To select text mode, the TEXTON ($C051) switch must be accessed 
(by a read or write operation). This can be done by executing a PEEK(49233) 
command from Applesoft or a LDA $C@51 command from assembler language. 
Alternatively, you can use the Applesoft TEXT command. 


The //c uses the 80COLOFF ($C00C) and 80COLON ($CQ@D) soft switches to 
control whether a 40- or 80-column text screen is to be displayed. If you write 
to 80COLOFF, then the 40-column display will be turned on. To turn on the 
80-column display instead, write to 80COLON. A program can always deduce 
which display mode is currently active by reading the 80COL ($C@1F) status 
location. If the number read is greater than 127 (that is, bit 7 is on), then the 
80-column display is on. 


Of course, the PR#3 command that is usually used to enter 80-column mode 
automatically takes care of properly setting the 80COL switches. Hence, you 
will usually not have to deal with them directly. 


You can see for yourself how the 80COL soft switches work by entering the 
system monitor so that you can easily access them. Before doing this, make 
sure that the standard 40-column mode is active by resetting the //c. Then 
enter CALL —151 from Applesoft and wait for the monitor's “*” prompt to 
appear. To tell the //c’s internal hardware to display an 80-column screen, 
store any number at 80COLON ($CQ@D) by entering the command 


COOGD:8 


As you will recall from Chapter 3, this command causes a 0 to be stored at 
$COOD. (Any other number could also have been stored.) As soon as you do 
this, the 8@-column display will be turned on. Since the special 80-column 
firmware required to fully support this display mode is not being used, how- 
ever, the system monitor's video output subroutine will not function properly 
and only the odd-numbered columns in the display will be used when infor- 
mation is sent to it. To return to a normal 4@-column display, enter the 
command 


CO0C:@ 


to activate the 80COLOFF ($C00C) switch. Again, any number, not just 0, can 
be stored at a soft switch location in order to activate the switch. 


Text Mode Memory Mapping 


There are significant differences in the method the //c uses to display 40- 
column and 8@-column text. We will begin with a discussion of the 40-column 


text display and then move on to explain how the 8@-column text display 
differs. 
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40-Column Text Mode 


In the 40-column text mode, the screen can be considered to be a matrix of 
40 columns by 24 rows. The video subroutines within the system monitor 
number the rows starting with @ at the top and ending with 23 at the bottom; 
the columns are numbered starting with @ at the left and ending with 39 at 
the right. Unfortunately, the Applesoft cursor positioning commands, VTAB 
and HTAB, start numbering the rows and columns with 1. We shall be using 
the system monitor’s numbering system in this section. 


In 40-column text mode, the //c translates the contents of one of two 1024- 
byte blocks of memory (called video RAM) into appropriate images on the 
video display. The first of these two blocks extends from $400 . . . $7FF and is 
referred to as pagel of text; the other block extends from $800... $BFF and 
is referred to as page2 of text. Note that the word “page” in this context means 
a block of 1024 bytes of video RAM. 


Each character that appears on the 4Q-column video display screen is 
defined by one byte in the currently active video page. This means that 64 of 
the bytes in the 1024-byte block are not used because there are only 960 
(40x24) screen locations to be displayed. These unused locations are called 
‘screen holes’ and are reserved for use by the firmware that controls the //c’s 
various I/O devices. 


To make things as simple as possible, it would be nice if the memory 
locations used by the video display were mapped linearly to their correspond- 
ing coordinates on the video display. If this were the case, then the memory 
location corresponding to any screen location would be given by 
BASE + (40xLINE)+COLUMN, where BASE is the starting address of the 
video page, LINE is the line number (@.. . 23), and COLUMN is the column 
number (@... 39). Unfortunately for all programmers, this is not how the //c 
handles its mapping of the video display. 


Instead, the //c assigns a unique base address to each line on the video 
screen that is not simply forty positions further into the video memory area 
from the start of the previous line. The byte at this address and the thirty- 
nine bytes that immediately follow it in memory are used to represent the 
forty characters on that video line. Table 7-2 shows the base addresses that 
are used for the pagel video display and shows how to calculate the address 
of the byte corresponding to any position on the video display (add 1024 to 
these addresses to calculate the corresponding page2 addresses). In general 
terms, if the video line number (@ . . . 23), in binary notation, is given by 

90Babcde 


where a... .e represent bit values, then the 2-byte base address is given by 
990081icd eababs#sG 

for pagel addresses or 
§9890018cd eababdas 

for page2 addresses. 


190 [___] Inside the Apple //c 


Table 7-2. Text screen video RAM addresses. 


Line Number Base Address | Line Number Base Address 
i) $400 12 $628 
1 $480 13 $6A8 
2 $500 14 $728 
3 $580 15 $7A8 
4 $600 16 $450 
5 $680 17 $4D0 
6 $700 18 $550 
7 $780 19 $5D0 
8 $428 20 $650 
9 $4A8 21 $6DO 
10 $528 22 $750 
11 $5A8 23 $7D0 


(a) 40-COLUMN SCREEN (columns 90... 39). The address corresponding to a position 
on the screen is equal to the base address for the line plus the column number. 

(b) 80-COLUMN SCREEN (columns @.. . 79). The address corresponding to a position 
on the screen is equal to the base address for the line plus one-half of the column 
number. If the column number is even, then this address in auxiliary memory is 
used; if it is odd, then the address in main memory is used. 


The base address for the line in which the cursor is currently located is 
always stored in two zero page locations, called BASL ($28) and BASH ($29). 
To calculate the decimal value of the base address for a given line on the 
pagel video display from Applesoft, simply move the cursor to the line and 
then calculate the quantity PEEK(40) + 256*PEEK(41). You can add 1024 to 
this result to convert it to a page2 base address. Table 7-3 shows a short 
program that does just this. It positions the cursor with the VTAB command 
and then calculates the base address using the method just described. 


If you want to calculate the base address for a line from assembly language, 
then use the following instructions: 


LDA #LINENUM sLINENUM=@ . . . 
JSR BASCALC ;BASCALC = $FBC1 


BASCALLC is a subroutine within the system monitor ($FBC1) that does the 
base address calculation for you. The result will be stored in BASL/BASH 
($28/$29) and will be equal to the pagel base address. To convert it to the 
corresponding page2 base address, add $04 to BASH. 


Why does the //c use this strange video mapping scheme? Well, back when 
the original Apple II was being designed, the main concern was not simplicity 
of software but rather simplicity of hardware. By changing to this mapping 
scheme, several chips from the original hardware design could be eliminated, 
thus making the Apple II less expensive and easier to manufacture. Seven 
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Table 7-3. BASE.ADDRESSES—a program to display the base 
addresses for each line on the video screen. 


06 REM "BASE.ADDRESSES" 

S@ TEXT : HOME 

66 DIM RWC24) 

1986 FOR I = 1 TO 24 

208 VTAB I 

300 RWCI) = PEEK €48) + 256 * PEEK 
€41) 

4800 NEXT I 

S@6 HOME 

688 PRINT “THE BASE ADDRESSES F 
OR EACH LINE ARE:": PRINT 

766 FOR I = 1 TO 24 STEP 2 

860 PRINT "LINE #31 - 13%:s TABC 
11)3;RWCI); 

908 PRINT TABC 20);"LINE #31; 
we". TABC 31);RWCI) 

18090 NEXT : PRINT 


years later the new and improved //c was released but, for the sake of com- 
patibility, the video mapping scheme was not changed. 


80-Column Text Mode 


Since the 80-column screen displays twice as many characters as its 40- 
column counterpart, another 1024-block of video memory is required to sup- 
port it. This additional block is not located in the //c’s main built-in memory; 
if this were the case, then the //c would be unacceptably incompatible with 
its older brothers. Instead, a 1K block of memory that is contained in the 
auxiliary memory area is used. 


This “extra” 1K block actually shares the same addresses used by the main 
display page, $400 ...$7FF, but, as we have just said, it is in a different 
physical location. When the //c’s 80-column display is active, the video cir- 
cuitry maps the standard pagel video page locations in main memory to the 
odd-numbered column positions on the 8@-column screen and the auxiliary 
memory locations to the even-numbered postions. So for any given line on 
the screen, the contents of columns 0,2,4, ... ,78 are found in auxiliary mem- 
ory and the contents of columns 1,3,5, ... ,79 are found in main memory. The 
base addresses for each line are the same as for the 40-column screen, however. 
The mapping scheme used by the 80-column screen is explained in Table 7- 
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You should now be able to see why only odd-numbered columns were used 
when you experimented with the 80COLON switch earlier. The standard 
system monitor video output subroutine presumes that a 40-column display 
is being used and so it accesses the $400 .. . $7FF area in main memory only. 
When 8@COL is ON, these locations correspond to odd-numbered columns on 
the video display; the locations corresponding to even-numbered columns are 
never accessed by this monitor subroutine. 


It is not permissible, of course, to have two physical memory locations, 
which share the same logical address, active at the same time. The //c uses 
soft switches to control which of the two $400 ...$7FF areas is to be active 
so that data can be stored to or read from any 80-column screen position 
directly. The switches used are PAGE2OFF ($C054) and PAGE2ON ($C055). 
They are used to select the main memory video RAM block and the auxiliary 
memory video RAM block, respectively, provided that the 80STORE switch 
is ON. If 80STORE is not ON, then, as we will see below, the PAGE2 switches 
are used to select between the two different 4Q-column video pages. 


The procedure to follow to store any value to a particular 80-column screen 
location is as follows: 


1. Select the proper mode for the PAGE2 switches by storing any number 
at 80STOREON ($C001). 


2. Determine the base address for the line required. 


3. Divide the required horizontal position (@...79) by two and add it to 
the base address. 


4. If the horizontal position is odd, then turn on the main $400 ...$7FF 
video page by storing any number at PAGE20FF ($CQ54). If the position 
is even, then turn on the auxiliary $400 ... $7FF video page by storing 
any number at PAGE20ON ($C@55). 


5. Store the byte at the address calculated in step 4. 
6. Reselect main memory by accessing PAGE2OFF ($C054). 


This is a fairly elaborate procedure but it is handled automatically if you 
are using the 80-column firmware for video output. It must be followed 
strictly, however, if you want to POKE data directly into the video screen 
from your own programs. Table 7-4 shows an Applesoft program called POKE8@ 
that uses this technique to display information on the video screen. 


Using Page2 of Text 


We have seen how the PAGE2 switches can be used to select between main 
and auxiliary memory if 80STORE is ON. If 80STORE is OFF, then PAGE2 
behaves in quite a different way. That is, it is used to select which of the two 
available 40-column text pages is to be displayed, the one from $400 ... $7FF 
(pagel) or the one from $800 .. . $BFF (page2). 
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Table 7-4. POKE80—a program to store any data byte in the 80- 
column video RAM area. 


9 REM “*POKE8@" 

198 HOME : PRINT CHR$ (€4);"PR# 
3° 

14@ INPUT “ENTER LINE ¥ (€@...23 
) eo 

15@ INPUT "ENTER COLUMN # C@... 
79): "sC 

168 INPUT "ENTER VALUE OF BYTE 
TO BE POKED TO SCREEN €9...2 
55): "sBY 

180 VTAB L + 1: REM MOVE CURSOR 
TO PROPER LINE 

198 BA = PEEK €4@) + 256 * PEEK 
€41): REM GET BASE ADDRESS 

208 BA = BA + INT CC / 2): REM 
ADD HORIZ/2 

2180 IF 2 * j$&INT €C / 2) € > C THEN 
POKE 49236,0: GOTO 2386 

220 POKE 49237,0: REM SELECT AU 
X MEMORY IF EVEN 

230 POKE BA,BY 

240 POKE 49236,0: REM SELECT MA 
IN MEMORY 

269 VTAB 22: END 


To select pagel, the PAGE2OFF ($C054) switch must be accessed and to 
select page2—you guessed it—the PAGE2ON ($C@55) switch must be accessed. 
You can always tell which page has been selected by reading the PAGE2 
($C01C) status location. If the number read is greater than 127, page2 is active. 


Pagel of the video display is the one that is invariably used by programs, 
especially if those programs are written in Applesoft. There are two good 
reasons for this. First, the //c’s standard video output subroutines always 
write screen information to the pagel memory area; if you wanted to send 
output in the usual way to page2, you would have to write your own subrou- 
tines to do this. Second, Applesoft programs are normally stored beginning 
at location $801, that is, within page2, which means that your program will 
be overwritten when the screen display changes. Although it is possible to 
load an Applesoft program so that it starts beyond page2 at $C@1, this involves 
using an awkward “preloading” program that looks something like this: 


108 POKE 1093,1:POKE 104,12:POKE 3972,9 
288 PRINT CHR$C4);"RUN YOUR.PROGRAM 


where YOUR.PROGRAM is the name of the program that you want loaded 
above page2. Line 100 in the above program stores $C@1 in the Applesoft 
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beginning-of-program pointer, TXTTAB ($67), and puts a $00 byte at $C00. 
(A zero byte must always be stored immediately before the start of a tokenized 
Applesoft program.) See Chapter 4 for a discussion of TXTTAB and other 
Applesoft pointers. 


Page2 does have its uses, however. For example, while pagel is being 
displayed, a program can be busily writing information on page2 and then, 
when page2 is complete, the PAGE20N switch can be accessed to immediately 
display page2. Then, while page2 is being displayed, pagel can be modified 
and later switched in by accessing PAGE2OFF. If this process is repeated, 
extremely good animation effects can be achieved and pages of written infor- 
mation can be displayed very smoothly. 


Note that a second 80-column text page (from $800... $BFF in main and 
auxiliary memory) can be selected using PAGE2ON with 80STORE set to 
OFF and 8@COL set to ON. This display mode is not supported by the //c’s 
firmware. 


Video Display Attributes: Normal, Inverse, Flash 


The //c text screens support three fundamental video display attributes: 


@ Normal video (white characters on a black background) 
@ Inverse video (black characters on a white background) 


e@ Flash video (blinking characters) 


Every printable ASCII character (that is, those with negative ASCII codes 
greater than $9F) can be displayed in normal video without restriction. There 
are restrictions, however, on what characters can be displayed in inverse and 
flash video, and these restrictions will depend on which of two possible 
characters sets available for the //c is currently active. 


The two characters sets that the //c supports are called the “primary” 
character set and the “‘alternative’’ character set. When the //c’s primary 
character set is in effect, it is not possible to display flashing or inverse 
lowercase characters. On the other hand, when the alternative character set 
is in effect, you will be able to display inverse lowercase characters but you 
will not be able to display flashing characters. The alternative character set 
also supports a set of 32 special symbols and icons called MouseText which 
the primary character set does not. We'll talk more about MouseText later in 
this section. 


One character set or the other can be selected by writing to one of the 
following two soft switch memory locations: 


ALTCHARSETOFF C$C@GE) toselect the primary character set 
or 


ALTCHARSETON C$C@BF) ~ toselect the alternative character set 
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When the //c is in its standard 40-column mode, the default setting of 
ALTCHARSET is off; when the 8@-column firmware is active, the default 
setting is on. The setting of ALTCHARSET can easily be changed at any time, 
however, in order to allow either character set to be used in both text modes. 


You can determine which character set is currently active by reading the 
ALTCHARSET status location at $CQ1E. If this location is greater than 127 
(that is, bit 7 is on), then the alternative set is currently active; otherwise, 
the primary set is active. The soft switch and status locations that relate to the 
//c’s character sets are summarized in Table 7-5. 


Table 7-5. Character set soft switches and status location. 


Address 
Hex (Dec) Symbolic Name Description 
$COOE (49166) ALTCHARSETOFF Select primary character set 
$COOF (49167) ALTCHARSETON Select alternative character 
set 
$CO1IE (49182) ALTCHARSET Status of character set 


switch (> = $80 if 
alternative set is active) 


The //c examines the two most-significant bits (bits 7 and 6) of each byte 
that has been stored within the video RAM area in order to determine which 
attribute is to be used to display the character that it represents. (We will 
examine the standard monitor subroutines used to store characters in the 
video RAM area later in this chapter.) 


If these two bits are “10” or “11,” then the character will be displayed in 
normal video. If they are “00,” the character will be displayed in inverse 
video. Finally, if they are ‘““@1,”’ then the character will be displayed either in 
flash video, if the primary character set is active, or in inverse video, if the 
alternative character set is active. These rules are summarized in Table 7-6. 


Table 7-6. Video attribute control bits. 


Bit 7 Bit 6 Video Attribute 
1 1 Normal 
0 Normal 
0 1 Flash (primary character set) 


Inverse or MouseText (alternative character set) 


0 Q Inverse 
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Table 7-7 shows how the //c interprets each of the 256 possible values that 
can be stored in its video display memory area, for both the primary and 
alternative character sets. You can see that the only difference between the 
two sets is that codes $40 ...$7F represent flashing alphabetic characters 
and special symbols when the primary set is active, whereas they represent 
the 32-byte MouseText character set and the inverse lowercase alphabetic 
and special characters when the alternative set is active. 


The program in Table 7-8 will show you visually how the //c’s video system 
interprets each of the 256 possible bytes that might be stored in a video RAM 
memory location. When you run this program, the name of the currently 
active character set will be shown at the top of the screen and then eight rows 
of 32 characters will be displayed, which represent bytes $00 through $FF. 
You can easily select the character set that you want to view by pressing “‘P”’ 
for primary or “‘A”’ for alternative after the symbols corresponding to each of 
the 256 bytes have been displayed. Notice how fast the display changes after 
you change the character set—this is indicative of a hardware-controlled 
change rather than a software-controlled change. 


MouseText 


MouseText symbols and icons are displayed on the video screen whenever 
a byte between $40 and $5F is stored in video RAM memory. As its name 
suggests, MouseText is primarily used by software that uses the Apple Mouse 
input device to point to and select commands and functions. 


Special subroutines in the //c’s 80-column firmware make it fairly simple 
to display MouseText using standard Applesoft PRINT statements. To do this, 


you must follow these steps (after the 80-column firmware has been activated 
and ALTCHAR is ON): 


@ Turn on inverse video. 
@ Enable the firmware’s handling of MouseText. 


@ Print the standard keyboard characters that correspond to the special 
MouseText characters that are to be displayed. 


@ Turn on norma! video. 


® Disable the firmware’s handling of MouseText. 


Here is an example of a short program that does just this: 


18980 PRINT CHR$C4);"PR43": REM SELECT 86- 
COLUMN FIRMWARE 

2608 PRINT CHR$C27); 

308 PRINT CHR$C15);"@ABCDEFGHI JKLMNOPQRSTUVWXYZE I" 
>CHR$C( 14); 

408 PRINT CHR$C24) 
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Table 7-8. CHAR.SETS—a program to display the //c’s primary and 
auxiliary characters sets. 


6 REM "CHAR.SETS" 
108 PRINT CHR$ €21): TEXT HOME 


1190 GOQOSUB 589 

126 FOR I = @ TO 255 

13@ HTAB 1+ 1 - 32 * € INT CI / 
32)) 

140 VTAB 3 + I / 32 

158 SL = PEEK €4@) + 256 * PEEK 
C41) + PEEK (€36) 

16@ POKE SL,I 

170 NEXT 

188 GOSUB 588 

1986 VTAB 20: HTAB 1: CALL - 95 
8 

C08 PRINT "CPIRIMARY OR CAILTER 


NATIVE? “3: GET A$: PRINT A$ 


219 IF A$ = “P®" OR AS = "“p" THEN 
POKE 49166,0: GOTO 189 

228 IF AS = "A" OR AS = "a™ THEN 
POKE 49167,80: GOTO 188 

230 IF A$ = CHR$ C27) THEN HOME 
: END 

248 GOTO 189 

586 VTAB 1: HTAB 1: CALL - 868 
> PRINT “THE °'; 

S510 IF PEEK €49182) > 127 THEN 
PRINT “ALTERNATIVE';: GOTO 
530 

520 PRINT “PRIMARY"; 

538 PRINT ™ CHARACTER SET I[S:" 

540 RETURN . 


We're getting a bit ahead of ourselves because this program uses four control 
characters that won't be discussed until the next section (see Table 7-11). 
Here’s what they mean: 

® CHR$(27)—Tell the firmware to display MouseText characters. 

@ CHR$(15)—Turn on inverse video. 

@ CHR§$(14)—Turn on norma! video. 

@e CHR§$(24)—Turn off the MouseText feature. 
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When the firmware is told to display MouseText and inverse video is on, 
the 80-column firmware maps the characters from ASCII code $C0 ('‘@’) 
through $DF (_’) to the MouseText characters having codes from $4@ through 
$5F. Thus, in the above program you will not see an inverse video display of 
keyboard symbols, but rather the complete MouseText character set. 


Standard Character Output Subroutines 


There is just one standard output subroutine that is used when a program 
running on the //c wants to send a character to the currently active output 
device; it is called COUT ($FDED), which stands for Character OUTput. The 
Applesoft PRINT command makes use of this subroutine. If the active output 
device is the video display screen, however, then COUT usually makes use of 
two other built-in subroutines called COUT1 ($FDFO), and C3COUT1 ($C307) 
to display the character at the proper position on the screen. These subrou- 
tines are summarized in Table 7-9. 


Table 7-9. Built-in output subroutines 


Address 
Hex (Dec) Symbolic Name Description 

$FDED (65005) COUT Sends a character to the cur- 
rently active output device. The 
negative ASCII code for the 
character is in the accumulator. 

S$FDFO (65008) COUTI1 Video output routine used when 
standard 4@-column mode is 
active. 

$C307 (49927) C3COUTI1 Video output routine used when 


the 80-column firmware is being 
used (this includes 80-column 
mode and the special 40-col- 
umn mode). 


As soon as COUT is called, the following code is executed: 
JMP CCSWL) 


which causes the //c to jump to a subroutine that begins at the address stored 
at CSWL ($36) and CSWH ($37). This subroutine is responsible for properly 
handling the character to be outputted (which is in the accumulator). If the 
current output device being used is the video display, then this usually means 
displaying the character on the screen at the current cursor position and 
advancing the cursor (and scrolling when necessary). If a special control 
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character is being outputted, then special video control subroutines may be 
invoked instead. (See below.) Note that by simply changing the address stored 
at CSWL/CSWH, any output subroutine can be installed on the //c. We will 
see how to do this later on. 


When ProDOS is being used, the address stored at CSWL and CSWH is 
actually that of a special ProDOS output subroutine. This subroutine will 
either store information on diskette or display it on the video screen, depend- 
ing on whether a diskette file is being written to. It also continuously checks 
to see whether a valid ProDOS command has been printed so that it can 
execute it immediately. ProDOS commands are easily identified because they 
are always preceded by a [control-D] character. 


If the ProDOS output subroutine needs to display the output on the video 
screen, then one of two built-in video output subroutines is used. One is called 
COUT! ($FDF@O), which is used when in standard 40-column mode. The other 
is called C3COUT1 ($C307) and is used when the 80-column firmware is being 
used. Before calling either of these subroutines, the 65C0@2 accumulator must 
be loaded with the ASCII code for the character to be printed (usually with 
the high bit set to one). If the high bit is zero, the character will be displayed 
with a special display attribute (either inverse or flashing). 


Let’s take a closer look right now at exactly what happens when a character 
is sent to the video display through the //c’s output link. 


Video Output 


As we have seen, COUT will normally pass control to one of two video 
output subroutines, depending on whether the 80-column firmware is active: 


® Control passes to COUT! ($FDFQ) if the //c is in standard 40-column 
mode. 


@ Control passes to C3COUT1 ($C307) if the 80-column firmware is active. 


These subroutines deal with the task of properly displaying a character on 
the screen or performing special video functions. 


After doing some initial housekeeping, both of these subroutines call VID- 
WAIT ($FB78). VIDWAIT will, if a carriage return (ASCII code $8D) is being 
printed, check the keyboard to see whether a [control-S] has been pressed. If 
it has, then VIDWAIT pauses until other ASCII code is entered before allowing 
the character to be printed. 


If the character being printed is not a control character (that is, its ASCII 
code is not between $80 and $9F), then control passes to VIDOUT ($FBFD) if 
standard 40-column mode is active, or STORCH ($C3B8) if the 80-column 
firmware is active. Both of these subroutines store the character in the video 
RAM page at the currently active cursor position. After the character has been 
displayed, the cursor is advanced and the subroutine ends. By the way, if 
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standard 40-column mode is active, the position of the cursor is defined by 
the values stored at CH ($24) and CV ($25), the horizontal and vertical cursor 
coordinates, respectively. If the 80-column firmware is being used, then the 
coordinates are kept at OURCH ($57B) and OURCV ($5FB) instead. 


If the character is a control character, then the subroutines VIDOUT1 
($FCO04) and DOCTL ($FBF4) will be used to determine whether a special 
action should be performed. VIDOUT1 is used when standard 4@-column 
mode is active and it reacts in a special way to four control characters only: 
[control-G] (bell), [control-H] (backspace), [control-J] (line feed), and [control- 
M] (carriage return). The actions that are taken when any of these control 
characters is encountered are shown in Table 7-10. All other control characters 
are ignored by VIDOUT1. 


Table 7-10. Special control codes used by both COUT1 and 
C3COUTI. 


Control Code Description 
[control-G] $87 Bell. Beep the speaker 


[control-H] $88 Backspace. Move the cursor one position to the left or 
to the end of the previous line if already at left edge. 


[control-J] $8A Line feed. Move the cursor down one line. 


[control-M] $8D Carriage return. Initiates a carriage return/line feed 
sequence that moves the cursor to the left position of 
the next line. 


DOCTL is used when the 80-column firmware is active. The first thing it 
does is to call the VIDOUT1 subroutine in order to handle a [control-G], 
[control-H], [control-J], or [control-M] character. If the character was one of 
these four, then DOCTL ends. If not, then tests are made for the presence of 
several other control characters which are listed in Table 7-11. If one of these 
special control characters is found, then the special function associated with 
it will generally be executed. It is possible, however, to disable these functions 
by entering an ESC [control-D] escape sequence from the keyboard before 
printing the control character. This sequence was discussed in Chapter 6, as 
was the ESC [control-E] sequence that is used to re-enable the special control 
characters. 


After a control character is handled by VIDOUT1 or DOCTL, the video 
output subroutine ends and control is passed back to the calling subroutine. 
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Table 7-11. Special control codes used by C3COUT1 (80-column 
firmware only). 


Control Code 


[control-K ] 
[control-L] 


[control-N | 
[control-O] 
[control-Q] 


[control-R ] 
[control-U] 


[control-V] 
[control-W] 
[control-X ] 


[control-Y] 
[control-Z | 


[control-[] 
[control-\] 
[control-]] 


[control-_] 


$8B 


$8C 


$8E 
$8F 
$91 


$92 
$95 


$96 


$97 


$98 


$99 
$9A 


$9B 


$9C 


$9D 


$9F 


Description 


Clear to end of screen. Clear from the current cursor 
position to the end of the screen. 


Form feed. Clear the screen and move the cursor to the 
home position (top left-hand corner). 


Normal. Turn on normal video display. 
Inverse. Turn on inverse video display. 


40-column. Keep 80-column firmware active, but move 
to a 40-column display. 


80-column. Move to an 80-column display. 


80-off. Turn off the 80-column firmware and return to 
40-column format. 


Scroll down. Scroll the display down one line leaving 
the cursor where it is. 


Scroll up. Scroll the display up one line leaving the 
cursor where it is. 


Mouse characters off. Disable the displaying of the spe- 
cial mouse character set. 


Home. Move the cursor to the home position. 


Clear line. Clear the entire line on which the cursor is 
positioned. 


Mouse characters on. Enable the displaying of the spe- 
cial mouse character set. 


Forward. Move the cursor forward one space with 
wraparound. 


Clear to end of line. Clear the screen from the current 
cursor position to the end of the line. 


Move cursor up one line (in the same column). If the 


cursor is already at the top, it will not move. 


Video Screen Windowing 


When the //c is first turned on, the standard output subroutines will auto- 
matically use the entire video screen for text display. It is possible to define 
a smaller ‘“‘window,’ however, into which all output is to be confined. The 
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advantage of defining such a window is that information outside the window 
will not usually be overwritten. When it becomes necessary to perform a 
scrolling operation, only the contents of the window will be moved; the 
information outside of the window will stay put. 


The dimensions of the text window can be set by adjusting four locations 
in zero page, described in Table 7-12. These locations are used to set the 
leftmost column position of the window (WNDLFT), the first line number 
used by the window (WNDTOP), the bottom line number used by the window 
plus one (WNDBTM), and the width, in characters, of the window (WNDWDTH). 


You can change the window parameters with simple Applesoft POKE state- 
ments. If you do change them, however, keep in mind the following two rules: 


® WNDBTM must always be greater than WNDTOP. 


® WNDWDTH+WNDLFT must not exceed the maximum display width 
(40 or 80). 


Table 7-12. Text window parameters. 


Address 
Hex (Dec) Symbolic Name Description 
$20 (32) WNDLFT Left side of window 


(40 col.:@...39) 
(80 col.: @... 79) 


$21 (33) WNDWDTH Width of window 
(40 col.: 1... 40) 
(80 col.: 1... 80) 


$22 (34) WNDTOP Top of window (@... 23) 
$23 (35) WNDBTM Bottom of window +1 (1... 24) 


After the window parameters have been changed, you can quickly and easily 
restore them to their initial default values by entering the Applesoft TEXT 
command. 


How COUT and C3COUTT1 Set the Video Attribute 


As we have seen, a character is normally displayed on the video screen by 
loading the 65C@2 accumulator with its ASCII code (with the high bit on) and 
then calling COUT ($FDED). COUT, in turn, calls either COUT1 ($FDF9), if 
the standard 40-column mode is active, or C3COUT 1 ($C307), if the 80-column 
firmware is being used. These subroutines take care of displaying the char- 
acter at the proper position on the screen. 
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How, then, does the //c determine whether to display the character in 
normal, inverse, or flash video? The answer depends on whether COUT! or 
C3COUT!1 is being used. 


If COUT1 is being used, then just before a printable ASCII code (that is, 
everything above $9F) is sent on to the main part of the video output routine, 
it is logically ANDed with the number stored at INVFLG ($32). The purpose 
of doing this is to adjust bits 6 and 7 of the outgoing character code so that 
they are equal to the values needed to select the required video attribute (see 
Table 7-6). The value stored at INVFLG is called a ‘“‘mask’’ because it will 
hide (clear to 0) those bits in the character code that are @ in the INVFLG 
byte, but will leave unaffected those bits that are 1 in the INVFLG byte. The 
three values for INVFLG, which are used to select the normal, flash, and 
inverse attributes, respectively, are set out in Table 7-13. 


Table 7-13. INVFLG mask values 


Value of 

INVFLG Video Attribute Effect on Character Code 
$FF Normal video No effect 
$7F Flash video Clears bit 7 
$3F Inverse video Clears bits 7 and 6 


INVFLG is location $32. 


Note: With $7F in INVFLAG, characters with values from $AQ...$BF will not flash, 
they will be displayed in inverse video (see text). 


With some exceptions, if you take any printable ASCII code and logically 
AND it with each of the three values for INVFLG, you will see that the bits 
will be set in accordance with the rules set out in Table 7-6. The exceptions 
relate to the use of the flash mask ($7F) with those characters having ASCII 
codes from $A@...$BF. Bit 6 of these codes is 0, so when bit 7 is cleared to @ 
by the flash mask, the attribute bits for an inverse character are set up and 
so the character won't flash. In an assembly-language program, you can 
circumvent this problem by always logically ORing a character code with 
the value $40 to force bit 6 to 1 before calling COUT1. This is exactly what is 
done by the Applesoft interpreter when you are running an Applesoft program. 


If C3COUT! is being used, then INVFLG is still examined before storing the 
character code in the video RAM area, but only bit 7 is checked. If it is one, 
the character will be displayed in normal video; ifit is zero, it will be displayed 
in inverse video. Although it is possible to display a flashing character on the 
80-column screen, the 80-column firmware does not support this attribute. 


The Applesoft NORMAL, FLASH, and INVERSE commands are all used to 
select the value stored at INVFLG. Keep in mind, however, that if the 80- 
column firmware is being used, the FLASH command will only cause an 
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inverse video display; if you want to display flashing characters, you will 
have to POKE bytes directly to the video RAM area. 


Changing Output Devices: The OUTPUT Link 


Character output on the //c is usually sent to built-in system monitor sub- 
routines that control the //c’s 40-column or 80-column video display screens. 
It is possible, however, to send output to other peripheral devices that are 
connected to the //c through its built-in interface ports. Examples of such 
devices are a disk drive, a printer, and a modem. 


The //c uses the same general method to handle output to such devices that 
it uses to handle input. This method was discussed in detail in Chapter 6 in 
the section describing the //c’s input link. 


We mentioned earlier that the first instruction in the standard COUT char- 
acter output routine looks like this: 


JMP €$0036) 


As we explained when discussing the input link, this is called an “indirect 
jump’ instruction and it will cause the //c to transfer control to the address 
stored at location $36 (low byte) and location $37 (high byte). If you are using 
the standard 40-column output routine, $36/$37 will contain the address of a 
subroutine in ProDOS that in turn usually calls COUT1 ($FDF@). (It could 
also call another subroutine to write information to a diskette file instead.) 
By changing the address stored at $36/$37, you can redirect the //c to any 
other output subroutine that you care to execute, including one used by an 
alternative output device. 


The symbolic name for locations $36/$37 is CSW (for character switch); $36 
by itself is called CSWL and $37 is called CSWH. CSW is commonly referred 
to as the “output link” or ‘‘output hook.” 

You will recall from Chapter 6 that the Applesoft ‘‘IN#s’’ command can be 
used to redirect input to port “s’’. In a similar way, you can use ““PR#s”’ to 
redirect output to port “‘s’’. When “PR#s’’ is entered, a program beginning at 
location $Cs@@ (where s is the port number), which is the first location in a 
ROM area dedicated to that port, is executed. Typically, the program begin- 
ning at this location will modify CSW so that it will point to a new output 
routine also contained in ROM. Note that if a PR#0@ command is entered, 
then the address of COUT1 ($FDF@), the //c’s standard 40-column output 
subroutine, will be stored at CSW. 


Subject to complications that arise whenever ProDOS is being used (see 
below), you can also change the output link directly by using the Applesoft 
POKE command or the assembler’s STA command to store the address of the 
new input routine directly into CSW at $36 and $37. This address can be in 
either ROM or RAM. 
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Designing a CSW Output Subroutine 


Any CSW output subroutine that will be used to replace the standard ones 
used by the //c must adhere to certain rules relating to the usage of 65C02 
registers. First of all, the output subroutine must examine the accumulator 
to determine which character code is being passed to it. Second, the subrou- 
tine must end with the A, X, and Y registers unaffected. If it is necessary to 
change the contents of these registers in the body of the subroutine, the 
registers must first be saved and then restored just before the subroutine ends. 


Replacing the Video Output Subroutine 


One common reason for changing the CSW output subroutine is simply to 
modify to the manner in which character output to the video display is 
handled. For example, you may want to perform one of the following tasks: 


@ Redefine the effect of control characters on the video display or define 
special actions to be performed by previously unused control characters. 


@ Prevent certain characters from being displayed. 


@ Translate character codes from one encoding system to another. 


For relatively minor changes such as these, it is not necessary to rewrite all 
the underlying code that takes care of positioning the cursor and displaying 
characters on the video display. What can be done instead is to install a new 
output subroutine that performs its special chores and then, if necessary, 
passes control to the standard output subroutine that can then handle the 
relatively complex chores of displaying a character on the screen and execut- 
ing special video-control commands. 


Here is an example of a short input subroutine that preprocesses character 
output before passing it on (if necessary) to the standard output subroutine: 


NEWOUT CMP #$87 sIs this a bell? 

BNE NOCHANGE sNo, so branch 

RTS ;Yes, so do nothing 
NOCHANGE JMP COUT1 ;Perform normal output 


This subroutine will prevent a bell character from ever being sent to the 
standard output subroutine (meaning that you won't hear that annoying beep 
when you make an error). It works by continually comparing each character 
code that is printed with the ASCII “bell” code (code $87) and by simply 
executing an RTS instruction if one is found. If the character code is not a 
bell, control passes directly to the standard video output subroutine. 


ProDOS and the Output Link 


The same restrictions referred to in Chapter 6 that apply when changing 
the input link when ProDOS is active also apply when changing the output 
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link. When ProDOS is first activated, the address stored in CSW is copied to 
an internal ProDOS output link location and then the address of a special 
ProDOS output subroutine is placed in CSW. This subroutine is responsible 
for detecting and handling any ProDOS commands that are printed (they are 
preceded by a [control-D] character) and for writing information to a diskette 
file if a ProDOS WRITE or APPEND command is in effect. If ProDOS is not 
currently writing to a file, then it will send output to the subroutine whose 
address is stored in the ProDOS output link. This is initially one of the 
standard video output subroutines. 


Normal attempts to store new addresses directly to CSW will obviously 
lead to a disconnection of ProDOS. Rather than repeat the explanations given 
in Chapter 6, we shall simply state how the output link must be changed to 
ensure that both ProDOS and the new output subroutine will be active. Any 
one of the following procedures may be used: 


@® Use the PR# command while in Applesoft direct mode (not within a 
program) or use the command 


PRINT CHR$C4);"PR¥5" 


from within a program (where ‘‘s”’ represents the port number). 


@ Use the BRUN command to load and execute an assembly-language 
program that stores the new output address into CSW. 


@ Use the POKE command to store the new input address directly into the 
ProDOS output link locations at $BE30 and $BE31. Alternatively, use 
the Applesoft CALL command or the system monitor GO command to 
execute an assembly-language program that stores the address directly 
into $BE30 and $BE31. 


If you are using ProDOS, you can also use a special form of the PR# 
command to properly install an output subroutine that is located anywhere 
in memory and not just in the ROM area for a port. The output subroutine 
must, however, begin with a 65C@2 “CLD” (clear decimal) instruction. To 
install the output subroutine, execute a statement of the form 


PRINT CHR$C4);"PR# Aaddr" 


from within an Applesoft program, where ‘‘addr’’ represents either the deci- 
mal starting address of the new output subroutine or, if preceded by ‘‘$’’, the 
hexadecimal starting address. 


Low-Resolution Graphics Mode 


The //c also supports two general graphic display modes called low-reso- 
lution graphics and high-resolution graphics. These modes are primarily used 
to present non-text information such as pictures, graphs, and maps and will 
now be described in detail, beginning with low-resolution graphics mode. 
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Turning on the Low-Resolution Graphics Display 


The easiest way to activate the //c’s low-resolution graphics display is to 
enter the Applesoft GR command from Applesoft direct mode. This command, 
however, selects only one of four possible versions of low-resolution graphics 
(namely, pagel with mixed graphics/text). As we will see later, other versions 
must be activated by directly setting some of the //c’s video soft switches. 


When the standard low-resolution graphics mode is in effect, colored “blocks” 
are displayed on the screen instead of text symbols. The dimensions of the 
screen are 4@ blocks wide by 48 blocks deep (or 40 blocks deep if a special 
mixed mode is in effect—see below). Column positions range from @ on the 
left to 39 on the right; row positions range from @ on the top to 47 on the 
bottom. 


There are two possible pages of low-resolution graphics that can be dis- 
played on the //c. The video RAM area that defines the first display screen 
(pagel) extends from $400 ...$7FF, and the area that defines the second 
(page2) extends from $800 ...$BFF. These are the same video RAM areas 
used to support the two pages of text mode. 


To turn on either page of standard low-resolution graphics, you must first 
ensure that the PAGE2 switches (PAGE2OFF and PAGE20N) can be used to 
select which of the two graphics pages is to be used rather than to select 
whether main memory or auxiliary memory is to be used. This can be done 
by writing to 80STOREOFF ($C000). (To be safe, you might also want to write 
to IOUDISON ($C07E) and DHIRESOFF ($C@5F) to ensure that double-width 
low-resolution graphics are not accidentally enabled. As we shall see in the 
next section, these commands will cause the circuitry that enables this special 
graphics mode to be disabled.) 


To turn on pagel of low-resolution graphics, the following switches must 
be “thrown” by reading from or writing to all of the following soft switch 
memory locations: 


TEXTOFF ($C050)—selects a graphics mode 
HIRESOFF ($C056)—selects low-resolution graphics 
PAGE20FF ($C054)—selects pagel 


To turn on page2, throw the following switches by reading from or writing 
to all of the following locations: 


TEXTOFF ($C@50) 
HIRESOFF ($C@56) 
PAGE20ON ($C@55) —selects page2 


In addition, it will be necessary to throw one of two other switches that 
control whether full screen graphics will be displayed or whether four lines 
of text will be “mixed in” at the bottom of the screen with 4@ lines of low- 
resolution graphics above them. The switches that control this are MIXEDON 
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($C053), which enables mixed graphics and text, and MIXEDOFF ($C@52), 
which enables full-screen graphics. Simply read from or write to these mem- 
ory locations to activate these switches. 


The switches that must be accessed to turn on the four different combina- 
tions of low-resolution graphics display modes are summarized in Table 7- 
14. 


Table 7-14. Low-resolution graphics display modes. 


Pagel of Low-Resolution Page2 of Low-Resolution 
Graphics (full-screen mode) Graphics (full-screen mode) 
TEXTOFF  ($C05@) TEXTOFF  ($CQ@50) 
HIRESOFF ($C0@56) HIRESOFF ($CQ@56) 
MIXEDOFF ($C052) MIXEDOFF ($CQ@52) 
PAGE2O0FF ($C054) PAGE20ON — ($C@55) 
Pagel of Low-Resolution Page2 of Low-Resolution 
Graphics (mixed mode) Graphics (mixed mode) 
TEXTOFF ($CQ50) TEXTOFF  ($C050) 
HIRESOFF ($C0@56) HIRESOFF ($C@56) 
MIXEDON ($C053) MIXEDON = _($C@53) 
PAGE2OFF ($C054) PAGE20ON — ($C@55) 


Low-Resolution Graphics Screen Memory Mapping 


Each block on the low-resolution graphics screen is defined by one-half of 
a byte (four bits) that is stored within the currently active video RAM area 
($400 ...$7FF for pagel or $800... $BFF for page2). The number stored in 
this half byte is the color code for the block (see the next section). Table 7-15 
shows the mapping scheme for each block on pagel of the low-resolution 
graphics screen; page2 addresses can be calculated by adding 1024 to the 
corresponding addresses for page1. Note that the base addresses for each pair 
of lines in the graphics screen (that is, 0/1, 2/3, 4/5, .. . 46/47 are the same as 
those for text lines 0, 1, 2,... ,23.) 


Low-Resolution Graphics Colors 


A special color code is stored in 4 bits of the byte in the video RAM page 
that corresponds to a particular block position. As Table 7-15 indicates, these 
4 bits are found in the top half of the byte (bits 4...7) or the bottom half 
(bits @...3), depending on the block’s position on the screen. Table 7-16 
contains a list of the color codes that can be stored in the byte in video RAM 
in order to generate the sixteen different colors that the low-resolution graph- 
ics mode supports. 
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Table 7-15. Low-resolution graphics video RAM screen addresses. 


Line Number Base Address | Line Number Base Address 
0,1 $400 24,25 $628 
2,3 $480 26,27 $6A8 
45 $500 28,29 $728 
6,7 $580 30,31 $7A8 
8,9 $600 32,33 $450 
10,11 $680 34,35 $4D0 
12,13 $700 36,37 $550 
14,15 $780 38,39 $5D0 
16,17 $428 49,41 $650 
18,19 $4A8 42,43 $6D0 
20,21 $528 4445 $750 
22,23 $5A8 46,47 $7D0 


(a) STANDARD LOW-RESOLUTION GRAPHICS (columns 0. . . 39). The address cor- 
responding to a position on the screen is equal to the base address for the line plus 
the column number. If the line number is even, then the lower 4 bits of the byte 
stored at this address are used to store the color code; if it is odd, the upper 4 bits 
are used. 


DOUBLE-WIDTH LOW-RESOLUTION GRAPHICS (columns @... 79). The address 
corresponding to a position on the screen is equal to the base address for the line 
plus one-half of the column number. If the column number is even, then this address 
in auxiliary memory is used; if it is odd, the address in main memory is used. If 
the line number is even, then the lower 4 bits of the byte stored at this address are 
used to store the color code; if it is odd, the upper 4 bits are used. 


(b 


Ne’ 


Double-Width Low-Resolution Graphics 


The //c also supports a special double-width low-resolution graphics mode 
that is not available on the earlier Apple II and Apple II Plus models. It is 
available as an option on the Apple //e but the big difference is that the 
Applesoft low-resolution graphics commands have been modified on the //c 
so that they will support this new mode. With the //e you have to write your 
own graphics commands before you can efficiently use this mode. 


Unlike standard low-resolution graphics, only one page of double-width 
graphics is available. Just as for 80-column text mode, the PAGE2 switches 
normally used to flip between display pages are instead used to select whether 
the part of the double-width graphics video page within main memory or 
auxiliary memory is to be used. 


Turning on Double-Width Low-Resolution Graphics 


The double-width low-resolution graphics can be displayed by first setting 
the TEXTOFF ($C050) soft switch to select a graphics mode, HIRESOFF 


7 / Character and Graphic Output and Video Display Modes [| 211 


Table 7-16. Low-resolution graphics color codes. 


Color Code Color 
$00 Black 
$01 Magenta 
$02 Dark blue 
$03 Purple 
$04 Dark green 
$05 Gray 1 
$06 Medium blue 
$07 Light blue 
$08 Brown 
$09 Orange 
SOA Gray2 
$0B Pink 
$OC Light green 
$0D Yellow 
$0E Aquamarine 
$OF White 


Note: these codes relate to bytes in main memory only (see Table 7-17 for the corre- 
sponding codes for bytes in auxiliary memory when using double-width low-resolution 
graphics). 


($C056) to select low-resolution graphics, and either MIXEDOFF ($C0@52) to 
select full-screen graphics or MIXEDON ($C@53) to select 40 lines of graphics 
with 4 lines of text. This can be done by executing the following assembly- 
language instructions: 


STA $CQ05@ 
STA $C856 
STA $C8@S2 Cor STA $0853) 


If you do this while you are in standard 40-column mode, the normal-width 
low-resolution graphics screen will be displayed. To enable the double-width 
graphics, three further soft switches must be set: 80COLON ($C@0D), IOU- 
DISON ($C07E), and DHIRESON ($CQ5E). As we saw when discussing 80- 
column text mode, the 80COLON switch is used to turn on the double-width 
display mode. The IOUDISON switch simply enables access to the DHIRE- 
SON switch. (As we will see in Chapter 10, the I/O locations used by the 
DHIRES switches are used by some mouse switches as well; the IOUDIS 
switch is used to select which switches are to be active.) The DHIRESON 
switch allows you to turn on the double-width graphics support circuitry. (It 
can be turned off by writing to IOUDISON ($C07E) and DHIRESOFF ($C0@5F).) 
To perform these steps from an assembly-language program, you would use 
the following three instructions: 
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STA $COO8D 

STA $CO7E 

STA $C@SE 

An easier way to turn on the double low-resolution graphics screen is to 
use standard Applesoft commands. To throw the same series of switches that 
we have just outlined from Applesoft, you would use this program segment: 


198 PRINT CHR$C4);"PR43": REM This sets 8@8COLON 

200 POKE 49278,0@: REM Enable access to DHIRES switch 
3808 POKE 49246,0: REM Access DHIRESON 

408 GR : REM This sets low-res graphics switches 


Once you have turned on double-width low-resolution graphics in this way, 
you can use the Applesoft graphics commands to draw on the screen. For 
example, to put a white border around the screen, execute the following 
program lines: 

S@8 COLOR= 15: REM Select white blocks 


600 HLIN 8,79 AT @: VLIN 8,39 AT 79: REM Top, Right 
700 HLIN 8,79 AT 39: VLIN 0,39 AT 0: REM Bottom, Left 


Double-Width Low-Resolution Graphics Screen 
Memory Mapping 


The //c displays double-width low-resolution graphics in much the same 
way that it displays its 80-column text screen. That is, the region of memory 
from $400 ...$7FF that resides on the 80-column text card (auxiliary mem- 
ory) is interleaved with the same region of memory on the motherboard (main 
memory). For a given low-resolution graphics screen line, all even locations 
are mapped to locations in auxiliary memory and all odd locations are mapped 
to locations in main memory. This mapping scheme is described in Table 7-15. 


You can select which area of screen memory is to be accessed by first 
ensuring that the 80STORE switch is on (by writing to location $CQ@1). This 
allows the PAGE2 switches to be used to select between main and auxiliary 
memory rather than pagel and page2 of graphics. PAGE2OFF ($C054) is used 
to select main memory and PAGE2ON ($C@55) is used to select auxiliary 
memory. As you can see, writing to the double-width low-resolution graphics 
screen is done in exactly the same way as writing to the 80-column text screen. 
After accessing auxiliary memory in this way, you should always turn off 
PAGE2 by accessing PAGE20FF ($C054). 


Note that there is a second page of double-width low-resolution graphics 
that occupies $800... $BFF in main and auxiliary memory. It can be selected 
by setting 80STOREOFF, 80COLON, and PAGE20N 


Double-Width Low-Resolution Graphics Colors 


Because of timing differences in interpreting auxiliary memory, the color 
codes stored in auxiliary memory to set the color of the low-resolution graph- 
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ics blocks are different from the standard ones set out in Table 7-16. These 
new color codes are set out in Table 7-17 in the standard color order of Table 
7-16. 


Table 7-17. Low-resolution graphics color codes for auxiliary 
memory locations. 


Color Code Color 
$00 Black 
$08 Magenta 
$01 Dark blue 
$09 Purple 
$02 Dark green 
$OA Grayl 
$03 Medium blue 
$0B Light blue 
$04. Brown 
$OC Orange 
$05 Gray2 
$0D Pink 
$06 Light green 
$0E Yellow 
$07 Aquamarine 
SOF White 


Built-In Support for Low-Resolution Graphics 


The easiest way to manipulate the standard low-resolution graphics screen 
is to use the Applesoft commands designed for this purpose. These commands 
are briefly summarized in Table 7-18. These commands will work with both 
the single- and double-width low-resolution graphics modes. 


Table 7-18. Applesoft low-resolution graphics commands. 


Command Description, 

GR Turns on pagel of low-resolution graphics in mixed mode and 
clears the display. 

COLOR = Selects a low-resolution color number. 

PLOT Plots a block on the screen. 

HLIN Draws a horizontal line on the screen. 

VLIN Draws a vertical line on the screen. 


SCRN Gets the color code at a given screen position. 
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Support for low-resolution graphics is also afforded by a series of subrou- 
tines contained within the //c’s system monitor. These subroutines are described 
in Table 7-20 and the zero page locations that they use are set out in Table 7- 
19. Note that some zero page locations must be properly set up before calling 
these subroutines. In particular, COLOR ($30) must contain the desired 4-bit 
color code (in both halves of the byte), H2 ($2C) must contain the destination 
location of a horizontal line before HLINE ($F819) is called, and V2 ($2D) 
must contain the destination location of a vertical line before VLINE ($F828) 
is called. Note, however, that these subroutines do not work properly when 
the double-width low-resolution graphics mode is enabled. Refer to Rob 
Moore’s article entitled “80-Column //e Low-Res Graphics” (noted in the 
references at the end of this chapter) for examples of assembly-language 
subroutines that do support the double-width mode. 


Table 7-19. Zero page locations used by low-resolution graphics 
subroutines. 


Address 

Hex (Dec) Symbolic Name Description 

$26 (38) GBASL Low byte of graphics screen line base 
address. 

$27 (39) GBASH High byte of graphics screen line base 
address. 

$2C (44) H2 Horizontal destination location for 
drawing a horizontal line. 

$2D (45) V2 Vertical destination location for 
drawing a vertical line. 

$2E (46) MASK Contains $F@ or $0F and is used to 


clear out the proper 4-bit area before 
setting the color for a low-resolution 


block. 


$30 (48) COLOR Contains the color code for the low- 
resolution block in the upper 4 bits 
and the lower 4 bits. 


High-Resolution Graphics Mode 


Of the two main graphics modes that the //c supports, high-resolution 
graphics mode is probably the most useful and exciting. This is because, as 
the name of this mode suggests, the points that can be plotted on the screen 
(called ‘‘pixels’’, for picture elements) are much smaller than low-resolution 
graphics blocks, thus allowing you to draw much finer shapes. This allows 
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Table 7-20. System monitor low-resolution graphics subroutines. 


Address 
Hex (Dec) Symbolic Name Description 
$F800 (63488) PLOT Plot a block using the current color 


at the position given by A (verti- 
cal) and Y (horizontal). 


$F819 (63513) HLINE Draw a horizontal line beginning 
from the position given by A (ver- 
tical) and Y (horizontal). The end- 
ing horizontal position is stored 
at H2 ($2C). 


$F828 (63528) VLINE Draw a vertical line beginning 
from the position given by A (ver- 
tical) and Y (horizontal). The end- 
ing vertical position is stored at 
V2 ($2D). 


$F832 (63588) CLRSCR Clear the full low-resolution 
graphics screen to black. 


$F836 (63542) CLRTOP Clear the top 40 lines of the low- 
resolution graphics screen to 
black. 


$F847 (63559) GBASCALC Put the base address for the line 
number contained in the accu- 
mulator (@...47) into GBASL 
($26) and GBASH ($27). 


$F864 (63558) SETCOL Set up the color mask at location 
COLOR ($30). On entry, A con- 
tains the color code (@... 15). 


$F871 (63601) SCRN Determine the color code stored 
at the location given by A (verti- 
cal) and Y (horizontal). 


you not only to place easily recognizable images on the screen but also to 
place more images on the screen. No wonder that virtually all popular games 
now being released for the //c use high-resolution graphics. 


Turning on the High-Resolution Graphics Display 


The //c supports two pages of high-resolution graphics, each of which are 
defined by a block of 8192 bytes. Pagel of high-resolution graphics is mapped 
to the area from $2000 ...$3FFF and page2 is mapped to $4000 .. . $5FFF. 
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The dimensions of the full-size high-resolution screens are 280 pixels wide 
by 192 pixels high. A mixed mode can also be defined, however, where the 
bottom 32 lines of pixels are replaced by 4 lines of text so that the dimensions 
of the graphics screens become 280x160. Numbering of both the pixel rows 
and the pixel columns begin at @ and the (0,0) position is at the top left-hand 
corner of the screen. 


Each pixel on the display screen is controlled by one bit of a byte in the 8K 
area associated with that screen and can be made to appear as one of eight 
colors, with some restrictions. If that bit is off, then a black dot will be 
displayed on the screen; if it is on, one of the five other colors (white, green, 
violet, orange, or blue) will be displayed. The two other colors are a duplicate 
white and black. We'll take a closer look at how to generate colored images 
later in this chapter. 


You can quickly turn on the two high-resolution screens from Applesoft by 
using the HGR and HGR2 commands. HGR turns on mixed-mode pagel] high- 
resolution graphics, and HGR2 turns on full-screen page2 high-resolution 
graphics. Let’s take a closer look at how the //c’s video soft switches can be 
used directly to select the various high-resolution graphics display modes. 


To turn on either page of standard high-resolution graphics, you must first 
ensure that the PAGE2 switches (PAGE2OFF and PAGE20N) can be used to 
select which of the two graphics pages is to be used rather than to select 
whether main memory or auxiliary memory is to be used. This can be done 
by writing to 80STOREOFF ($C000). (To ensure that double-width high- 
resolution graphics are not accidentally enabled, you should also write to 
IOUDISON ($C07E) and DHIRESOFF ($C@5F). As we shall see in the next 
section on double-width high-resolution graphics, this will disable the cir- 
cuitry that enables this special graphics mode.) 


The high-resolution graphics displays are turned on in much the same way 
as the low-resolution displays. In fact, the only difference is that the HIRESON 
($C@57) soft switch must be accessed instead of the HIRESOFF ($C@56) soft 
switch. To turn on pagel, read from or write to the following locations (with 
80STORE in the off position): 


TEXTOFF ($C050)—selects a graphics mode 
HIRESON ($C@57)—selects high-resolution graphics 
PAGE2OFF ($C054)—selects pagel 


To turn on page2, simply access PAGE20N ($C@55) instead of PAGE2OFF. 


You can also control whether full screen graphics are to be displayed or 
whether four lines of text are to appear at the bottom of the screen instead of 
the last 32 lines of the graphics page. The switches to use to control these two 
options are MIXEDON ($C@53), which selects the graphics-text combination, 
and MIXEDOFF ($C@52), which selects full-screen graphics. 


Table 7-21 summarizes the switches that must be set to select each of the 
four possible combinations of high-resolution display modes. 
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Table 7-21. High-resolution graphics display modes. 


Pagel of High-Resolution Page2 of High-Resolution 
Graphics (full-screen mode) Graphics (full-screen mode) 
TEXTOFF ($CQ50) TEXTOFF  ($C@50) 
HIRESON = _($C@57) HIRESON = ($C@57) 
MIXEDOFF ($C052) MIXEDOFF ($C@52) 
PAGE2OFF ($C054) PAGE2ON = ($C@55) 
Pagel of High-Resolution Page2 of High-Resolution 
Graphics (mixed mode) Graphics (mixed mode) 
TEXTOFF  ($C0@5@) TEXTOFF  ($C@50) 
HIRESON —_($C@57) HIRESON — ($C0@57) 
MIXEDON = ($C@53) MIXEDON = ($C@53) 
PAGE2O0FF ($C054) PAGE20ON = ($C@55) 


High-Resolution Graphics Screen Memory Mapping 


The //c uses 40 consecutive bytes in the applicable high-resolution screen 
video RAM memory area ($2000 . . . $3 FFF, pagel, or $4000 .. . $5FFF, page2) 
to define the contents of each 280-pixel graphics line. The most-significant bit 
of each of these bytes, however, is not used for display purposes (it is used to 
select which of two sets of four colors can be displayed). Each of the 40x7 = 280 
active bits in these 40 bytes corresponds to a unique column position. The 
seven pixels corresponding to each byte in memory are displayed on the screen 
in reverse order of their positions within the byte. That is, the first pixel 
displayed on the screen (the one farthest to the left) corresponds to bit 0, the 
next one corresponds to bit 1, and so on. If a bit is set to ‘‘1’’, then the pixel 
will be illuminated; if it is cleared to “O”’, it will be turned off. 


As with the text screen, the high-resolution pagel and page2 memory areas 
are not mapped linearly to the video screen. To determine the memory address 
corresponding to a particular pixel, it is first necessary to calculate the base 
address for the line in which it appears. Reverting to binary notation for a 
moment, if the line number (@. . . 191) is given by 


abcdefgh 


(where a...h represent values of bits 7...@, respectively), then the base 
address for that line is given by the two bytes 


@ppfohcd eababdas 
where 


pp = 81 for pagel 
pp = 10 for pagee 
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The base addresses for each line of the high-resolution display are set out 


in Table 7-22. To convert these addresses to the corresponding page2 addresses, 
add $2000 (8192). 


Table 7-22. High-resolution graphics video RAM screen addresses. 


Line Number Base Address Line Number _ Base Address 
0-7 $2000 + $400xRLN 96-103 $2228 + $400xRLN 
8—15 $2080 + $400xRLN 104-111 $23A8 + $400xRLN 
16—23 $2100+ $400xRLN 112-119 $2328 + $400xRLN 
24-31 $2180+ $400xRLN 120-127 $23A8 + $400xRLN 
32-39 $2200 + $400xRLN 128-135 $2050 + $400xRLN 
40—47 $2280 + $400xRLN 136-143 $20D0 + $400xRLN 
48-55 $2300 + $400xRLN 144-151 $2150+ $400xRLN 
56-63 $2380 + $400xRLN 152-159 $21D0+$400xRLN 
64-71 $2028 + $400xRLN 160—167 $2250+ $400xRLN 
72-79 $20A8 + $400xRLN 168-175 $22D0+ $400xRLN 
80-87 $2128+ $400xRLN 176-183 $2350 + $400xRLN 
88—95 $22A8 + $400xRLN 184-191 $23D0+ $400xRLN 


RLN = relative line number. This number is equal to the actual line number minus 
the first line number in the group of eight within which it falls in the above table. For 
example, RLN for line #83 is 3 (83-80). 


(a) STANDARD HIGH-RESOLUTION GRAPHICS (columns @...279). The address 
of the byte corresponding to a pixel position is equal to the base address for the 
line plus the horizontal pixel position divided by 7. The bit position within this 
byte corresponding to the pixel is the horizontal pixel position modulo 7. 

(b) DOUBLE-WIDTH HIGH-RESOLUTION GRAPHICS (columns @ ...559). The address 
of the byte corresponding to a pixel position is equal to the base address for the 
line plus the horizontal pixel position divided by 14. If the horizontal pixel position 
modulo 14 is between 0-6, this address in auxiliary memory is used; if it is between 
7—13, this address in main memory is used. The bit position within the byte 
corresponding to the pixel is the horizontal pixel position modulo 7. 


The byte position number (@ . . . 39) for a particular pixel column (remem- 
ber that 7 columns are defined by one byte) is given by the quotient of 


X/7 


where X is the column number (0...279). To access this byte, the 65C@2 
indirect-indexed addressing mode, “(zp),Y’’, can be used (‘‘zp”’ refers to any 
zero page location that contains the low half of the base address for the line; 
zp + 1 contains the high half). The bit number within this byte that is mapped 
to the column is given by the remainder generated by the X/7 calculation 
(that is, X modulo 7). This is the bit that can be set to 1 to illuminate a pixel 
on the screen or cleared to @ to turn it off. 
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Pixels on the high-resolution graphics screen can be one of eight colors: 
black1, black2, white1, white2, green, orange, violet, and blue. These are the 
eight colors that can be set using the Applesoft HCOLOR = command. Because 
of the way the high-resolution graphics circuitry works on the //c, however, 
you cannot display all colors at all positions on the high-resolution screen. 
For example, green and orange pixels can appear only in odd-numbered 
columns, and violet and blue pixels can appear only in even-numbered col- 
umns. In addition, in some circumstances that we will refer to in a moment, 
you cannot display blue and orange pixels close to green and violet pixels, 
and vice versa. 


If you are plotting points in a particular color, you must ensure that, even 
if a particular column is selected, you do not illuminate pixels in that column 
if it is a restricted column for that color, or else the color will be wrong. This 
is handled automatically by the Applesoft high-resolution graphics com- 
mands and can be done from assembly language by logically ANDing the byte 
that is to be stored in the video page with the appropriate color mask. This 
mask will ensure that no ‘1’’s can appear in restricted columns. Table 7-23 
sets out the column restrictions and color masks for each of the eight allowed 
high-resolution graphics colors. 


Table 7-23. High-resolution screen display information. 


Value of 
Applesoft High-Order Bit Display Byte Mask Column 
Color HCOLOR= of Display Byte Even Byte Odd Byte  Restr. 


Blackl 0 fi) $00 $00 None 
Green 1 1) $2A $55 Odd only 
Violet 2 4) $55 $2A Even only 
Whitel 3 fy) $7F $7F None 
Black2 4 l $80 $80 None 
Orange 5 1 $AA $D5 Odd only 
Blue 6 1 $D5 $AA Even only 
White2 7 l $FF $FF None 


Not all colors can be used at the same time. The most- significant bit of the 
byte that defines the pixel must be cleared to @ in order to have a ‘1’ in the 
byte displayed as green/violet or set to 1 to have it displayed as orange/blue 
(for an odd/even column). A side effect of this phenomenon is that it is not 
possible to generate green and violet pixels if they are defined by bits in the 
same byte as orange and blue pixels. 
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To get white displayed on the screen, two horizontally adjacent pixels on 
the screen must be set to 1. If this is done, then both pixels will be displayed 
as white. Note that there are two different types of white, whitel and white2. 
The only difference between these two colors is the status of the high-order 
bit within the byte that defines the two adjacent pixels. Note, also, that it is 
not possible to get a single white dot surrounded by black because an isolated 
‘1’ bit will be interpreted as either green/violet or orange/blue. 


In summary, the standard high-resolution screen looks at each horizontally 
adjacent pair of bits to determine which of four colors is to be displayed: 
black1 (00), whitel (11), green (01), or violet (10), if bit 7 in the byte in which 
they are contained is off; or black2 (00), white2 (11), orange (01), or blue (19), 
if bit 7 is on. 


It should now be clear that because of the column restrictions on colors 
other than black and white, the effective screen resolution is only 140x192 for 
color graphics even though it is possible to control the states of all 280 
horizontal pixels individually. 


Animation with High-Resolution Graphics 


One of the main reasons for including two high-resolution graphics pages 
on the //c was to allow you to generate high-quality animation effects. Ani- 
mation is typically simulated on a computer by first drawing a shape, pausing, 
erasing the original shape, and then redrawing it at its new position. By 
repeating this procedure, the effect of motion is created. 


If this procedure is used in connection with one display screen only, then 
the problem of “‘flickering’’ can arise and the first shape will not appear to 
change smoothly into the next. This effect is observed because the screen is 
continually being “redrawn” by the electronic circuitry within the video 
display unit before the first shape has been completely erased and redrawn. 
If the shape is complex enough, a partially erased or partially redrawn shape 
will be displayed for discernible periods of time. 


One way of getting around this problem is to draw the next shape in an 
animation sequence on the graphics page that is not being displayed and 
then, after it has been so drawn, to throw the switch that activates that page 
of graphics. Then, while that page is being displayed, the shape on the other 
page can be erased and repositioned, and then that page can be displayed 
again. The net effect is that all erasing and redrawing is done on the screen 
that is not being displayed and so flickering will be eliminated. If Applesoft 
graphics commands are being used, the page that is being written to can be 
controlled simply by adjusting the value of the byte located at $E6. To write 
to pagel, this byte must be set equal to $20; to write to page2, it must be set 
equal to $40. 


One problem with using the two pages of high-resolution graphics in this 
way, however, is that another 8K of memory must be devoted for use by the 
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display screen and is unavailable for use by the program. For larger programs, 
this can be a major limitation indeed. 


Fortunately, there is an alternative method that can be used to achieve 
flicker-free animation: moving a shape while the video display unit is not 
actually refreshing the screen. This method can be used on the //c and //e only 
and not on the earlier Apple II and Apple II Plus models. 


The video display unit is continually “refreshing” the screen by redrawing 
all the scan lines that define the display screen. It does this by moving an 
electron beam in a zig-zag motion across the display screen from top to 
bottom. After all of the video scan lines have regenerated in this way, there 
is a synchronization delay during which the electron beam is repositioned to 
the upper left-hand corner of the screen awaiting the arrival of the next video 
frame. This delay occurs every 1/60 of a second. 


The delay between the end of one zig-zag scan and the beginning of the next 
one is called the vertical blanking interval, and during this time the screen 
display is not being altered in any way. Thus, if during this vertical blanking 
interval we could change the data bytes that define the screen display image 
in such a way as to cause the shape being animated to be erased and reposi- 
tioned, there would be no discernible flickering. 


Well, we can! It is possible, under software control, to enable a special 
vertical blanking (VBL) interrupt signal, that will interrupt the 65C@2 at the 
beginning of every vertical retrace operation (that is, 6@ times per second). If 
your interrupt- handling subroutine is properly set up, you can use it to erase 
and redraw your animated shape before the retracing operation ends (it lasts 
for about 12,000 machine cycles) so that there will be no flickering. 


We'll defer a complete discussion of how to activate the VBL interrupt to 
Chapter 10 where we'll also discuss how it is used in connection with the 
Apple Mouse. 


Double-Width High-Resolution Graphics 


The //c also supports an impressive double-width high-resolution graphics 
display mode. When it is used, the other ‘‘half’”’ of the double-width graphics 
screen is stored in auxiliary memory. Unlike the double-width low-resolution 
graphics mode, however, neither Applesoft nor the system monitor contains 
any commands or subroutines that allow you to use this mode directly. 
Programs are available, however, that will allow you to take advantage of the 
power of this graphics mode; some of them are listed in the references at the 
end of this chapter. 


The double-width high-resolution graphics mode has a pixel resolution of 
560x192, rather than the standard 280x192, and allows a total of sixteen 
colors! These colors are the same ones that can be displayed when using 
standard low-resolution graphics. 
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Turning on Double-Width High-Resolution Graphics 


It is relatively simple to activate the double-width high-resolution graphics 
mode. The first step is to turn on pagel of high-resolution graphics mode as 
you would normally. This can be done by executing the following sequence 
of instructions: 


STA $C050—TEXTOFF (enables graphics) 
STA $C057—HIRESON (high-resolution) 
STA $C053—MIXEDON (mixed graphics/text) 


The next step is to enable the double-width mode by setting the 80COLON 
($C@OD), IOUDISON ($C07E), and DHIRESON ($CQ5E) switches to enable 
the double-width graphics circuitry. You can set these switches by executing 
these three instructions: 


STA $COOD—80COLON (sets double-width switch) 
STA $C07E—IOUDISON (enables access to DHIRES switch) 
STA $CO5E—DHIRESON (enables double-width graphics) 


You can also turn on the same series of switches from Applesoft by running 
the following program: 


160 PRINT CHR$C4);"PR#3": REM THIS SETS 88COLON 

208 POKE 49278,@: REM ENABLE ACCESS TO DHIRES SWITCH 
3086 POKE 49246,8: REM ACCESS DHIRESON 

400 HGR : REM THIS SETS HIGH-RES GRAPHICS SWITCHES 


Once the double-width graphics screen has been activated, the next step is 
to draw something on it. This is easier said than done, however, because the 
Applesoft high-resolution graphics commands work only with the standard 
280-column screen. If you attempt to use them, you will see rather strange 
effects, since only the screen area in main memory will be used. For example, 
try entering the Applesoft commands 


HCOLOR=3 
HPLOT 8,9 TO 279,98 


If you were to do this for normal-width high-resolution graphics you would 
see a horizontal white line drawn across the top of the screen. With double- 
width graphics enabled, however, the white line is “broken”’ at forty different 
positions. The data bytes for these positions are contained in auxiliary mem- 
ory and are not dealt with by Applesoft. 


See the references at the end of this chapter for sources of programs that 
support double-width high-resolution graphics. 


Double-Width High-Resolution Graphics Screen Memory 
Mapping 


You will recall that when the //c is displaying double-width text (that is, 80 
columns of text) or double-width low-resolution graphics, it interleaves the 
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video RAM bytes in main memory with those contained at the same addresses 
in auxiliary memory. Well, double-width high-resolution graphics works in 
exactly the same way. The region of memory from $2000 ...$3FFF in main 
memory is interleaved with an 8K block of memory having the same addresses 
on the extended 80-column text card in such a way that of the 8@ consecutive 
bytes used to define the contents of one line (recall that only 40 were required 
for standard high-resolution graphics), the even ones (0, 2,4, .. . ,78) are found 
in auxiliary memory and the odd ones in main memory. The mapping scheme 
used is summarized in Table 7-22. 


Just as in standard high-resolution graphics mode, each of the 80 bytes 
corresponds to seven consecutive pixels on the screen. The first pixel is con- 
trolled by bit 0, the next one by bit 1, and so on. Bit 7 is not used. 


The 80STORE switch enables you to select which of the two $2000 .. . $3FFF 
blocks you want to read from or write to. By setting 830STOREON (by writing 
to location $C0@1), the PAGE2 switches can be used to select either the 8K 
block in main memory, by accessing PAGE2O0FF ($C@54), or the 8K block in 
auxiliary memory, by accessing PAGE2ON ($C055). After you have written to 
screen memory, you should always access PAGE2OFF ($C@54) to re-enable 
main video memory. 


Note that there is a second page of double-width high-resolution graphics 
that occupies $4000... $5FFF in main and auxiliary memory. It can be selected 
by setting 80STOREOFF, 80COLON, and PAGE20N. 


Double-Width High-Resolution Graphics Colors 


When we discussed normal high-resolution graphics, we saw how the //c 
interprets two adjacent pixels as one of four colors. Not surprisingly, when 
double-width graphics are used, the //c interprets four adjacent pixels as one 
of sixteen different colors (2%4= 16). The 4-bit pixel patterns that give rise to 
these colors are set out in Table 7-24. Since pixels are displayed on the video 
screen in the reverse order that they appear in the video RAM data bytes, 
these patterns must be reversed to obtain the corresponding bit patterns that 
must be stored in memory to generate them. 

Note that the high bit of each of the 8 bytes that is used to store information 
for each line of double-width graphics is not used at all—not even to affect 
the colors generated by the bits within that byte (as it is in normal high- 
resolution graphics). 


Built-In Support for High-Resolution Graphics 


Applesoft contains several commands that are used to control various aspects 
of the two standard high-resolution graphics screens. These commands are 
summarized in Table 7-25. 


The //c’s system monitor does not support high-resolution graphics at all. 
The Applesoft ROM does, however, contain several built-in subroutines that 
can be used from an assembly-language program in order to draw points, 
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Table 7-24. Bit patterns for the sixteen double-width high-resolution 
graphics colors. 


Color 


Black 

Dark red 
Dark blue 
Purple 
Dark green 
Gray | 
Medium blue 
Light blue 
Brown 
Orange 
Gray2 

Pink 

Green 
Yellow 
Light green 
White 


Bit Pattern 


0000 
1000 
0100 
1100 
0010 
1010 
0110 
1110 
0001 
1001 
0101 
1101 
0011 
1011 
O111 
1111 


Table 7-25. Applesoft high-resolution graphics commands. 


Command 


HGR 


HGR2 


HCOLOR= 
HPLOT 
DRAW 
XDRAW 


ROT = 
SCALE= 


Description 


Turns on pagel of high-resolution graphics in mixed mode 
and clears the screen. 


Turns on page2 of high-resolution graphics in full-screen 
mode and clears the screen. 


Selects the high-resolution color number. 
Plots pixels and draws lines on the screen. 
Draws a shape on the screen in the color set by HCOLOR=. 


Draws a shape on the screen using the complement of the 
color already existing at each plotted point. 


Sets the rotation factor used when drawing shapes. 


Sets the scale factor used when drawing shapes. 


lines, and shapes. These subroutines are set out in Table 7-27 and the zero 
page locations that they use are set out in Table 7-26. 


Note that these commands and subroutines do not support double-width 
high-resolution graphics.at all. 
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Table 7-26. Zero page locations used by the Applesoft high- 
resolution graphics subroutines. 


Address 
Hex (Dec) Symbolic Name Description 


$EQ (224) HHORIZ (low) Horizontal coordinate (@... 279). 
$E1 (225) (high) 


$E2 (226) HVERT Vertical coordinate (@... 191). 

$E4 (228) HMASK High-resolution color mask. 

$E6 = (230) HPAG High-resolution page designation. 
Set this byte to $20 for pagel and 
to $40 for page2. 

$E7 = (231) SCALE Applesoft SCALE= factor for 
shapes. 

$F9 (249) ROT Applesoft ROT = factor for shapes. 


Further Reading for Chapter 7 


Standard reference works ... 


80-Column Text Card Manual, Apple Computer, Inc., 1982. 
Extended 80-Column Text Card Supplement, Apple Computer, Inc., 1982. 


Note: the above two reference manuals are written for the optional 80- 
column text card used on the Apple //e only. However, much of the 
information in them is directly applicable to the built-in 80-column dis- 
play on the //c as well. 


On changing the output link ... 


G. Little, ““Paged Printer Output for the Apple’, Micro, October 1980, pp. 
47—48. This article demonstrates how to change the output link so that 
the format of printed output can be controlled. 


On ProDOS and the output link ... 


C. Fretwell, “Setting I/O Hooks in ProDOS”, Call -A.P.P.L.E., April 1984, 
p.39 


On high-resolution graphics ... 


B. Bishop, ‘‘Apple II Hires Picture Compression’, Micro, November 1979, 
p. 17. 
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L. Spurlock, “Understanding Hi-Res Graphics”’, Call -A.P.P.L.E., January 
1980, p. 6. An analysis of the high-resolution mapping scheme. 


B. Bishop, “Apple II Hi-Res Graphics: Resolving the Resolution Myth”, 
Apple Orchard, Fall 1980, pp. 7-10. Discussion of the mapping of the high- 
resolution graphics screen. 


E.C. So, “Picture Compression”, Call -A.P.P.L.E., May 1982, p. 21. 


R.T. Simoni, Jr., ““A New Shape Subroutine for the Apple’, Byte, August 
1983, pp. 292-309. A new method for drawing high-resolution shapes that 
leads to flicker-free animation. 


On double-width graphics ... 


R. Moore, ‘‘80-Column //e Low-Res Graphics’, Call -A.P.P.L.E., July 1983, 
pp. 9-13. A set of subroutines supporting double-width low-resolution 
graphics is presented in this article. 


D. Worth, “Hi-Res Double Play”, Softalk, July 1983, pp. 12@—126. A descrip- 
tion of the Apple //e’s double-width high-resolution graphics. It is appli- 
cable to the //c as well. 


P. Baum and L. Roddenberry, ““Applesoft Brushes for Double Hi-Res Art’’, 
Softalk, September 1983, pp. 82-99. Programs are presented that support 
double-width high-resolution graphics. 


A. Watson III, “True Sixteen-Color Hi-Res’’, Apple Orchard, January 1984, 
pp. 26—46. An excellent discussion of the theory of double-width high- 
resolution graphics. A set of assembly-language driver programs are also 
presented which can be called from Applesoft. 


Extended 80-Column Text Card Supplement, Apple Computer, Inc., 1982. 


R.R. Devine, “Double Hi-Res Graphics I’’, Nibble, May 1984, pp. 81-96. 
Another detailed discussion of the double-width display mode. 


R.R. Devine, “Double Hi-Res Graphics II’, Nibble, August 1984, pp. 122- 
129. 


R.R. Devine, “Double Hi-Res Graphics III’, Nibble, September 1984, pp. 
139-144. 


On video display theory ... 


J. Hockenhull, “Video Interfacing”, Call -A.P.P.L.E., June 1982, pp. 9-13. A 
good discussion of the theory of video display technology. 


J. Mazur, ‘‘Hardtalk’’, Softalk, April 1983, pp. 215—225. A technical analysis 
of the Apple II video display system. 


J. Mazur, “Hardtalk’’, Softalk, May 1983, pp. 91-98. A technical analysis of 
the Apple II video display system. 
R.H. Sturges, Jr., “Double the Apple II's Color Choices”, Byte, November 


1983, pp. 449-463. A good explanation of how the Apple II generates 
colored images. 
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Table 7-27. Applesoft ROM high-resolution graphics subroutines. 


Address 
Hex (Dec) Symbolic Name Description 

$F3D8 (62424) HGR2 Turns on high-resolution page2 
(full-screen) and clears it to black. 

$F3E2 (62434) HGR Turns on high-resolution pagel 
(with 4 lines of text) and clears 
it to black. 

$F457 (62551) HPLOT Plots a colored dot at the posi- 
tion given by A (vertical), Y (hor- 
izontal high) and X (horizontal 
low). 

$F53A (62778) HLIN Draws a line from the last plot- 


ted dot to the position given by 
Y (vertical), X (horizontal high), 
and A (horizontal low). 


$F601 (62977) DRAW Draws the shape whose data area 
is pointed to by Y (high) and X 
(low) using the rotation factor in 
A. The shape is drawn by invert- 
ing the existing screen bits that 
are used by the shape. 


$F65D (63069) XDRAW Same as DRAW except that when 
the shape is plotted, the existing 
screen bits and the shape bits 
are logically exclusive-ORed with 
each other to determine the new 
value of the screen bit. 


$F6EC (63212) SETHCOL Sets the active code to the value 
of X (@...7). These are the eight 
colors defined by the Applesoft 
HCOLOR= command. 


Memory Management 


As we saw in Chapter 2, the 65C@2 microprocessor that controls the //c is 
capable of addressing only 65536 (64K) different logical memory locations. 
These locations have addresses that range from $0000 to $FFFF. A standard 
/ic, however, contains many more physical memory locations than this. 


A detailed memory map of the //c was presented at the end of Chapter 2. In 
summary, the memory that is built-in to the //c is as follows: 


@ 64K of main RAM memory 

10K of ROM memory for Applesoft 

2K of ROM memory for the standard system monitor 
0.25K of I/O memory 


3.75K of ROM memory that contains extensions to the standard system 
monitor and support for built-in peripheral devices (two serial ports, 
mouse port, disk drive, and 80-column display) 


@ 64K of auxiliary RAM memory (1K of which is used by the 80-column 
display circuitry) 


If you add up all the numbers, the total comes to 144K. This may seem a 
bit surprising since we just said that the //c’s 65C@2 microprocessor is capable 
of addressing only 64K locations. How is all that extra memory used? To 
answer this, you must realize that the 65C@2 can use as much memory as you 
care to provide to it so long as there are never more than 64K physical memory 
locations active at the same time and so long as no two active memory 
locations are associated with the same address. Several soft switches are 
available on the //c that allow you to easily select which one of those duplicated 
memory areas is to be active. The technique used to select memory in this 
way is called “bank-switching.’’ 


In this chapter, we will be looking at the soft switches that the //c uses to 
control usage of its duplicated memory areas, and we will show how they can 
be used to take advantage of all of the memory available on the //c. 
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16K Bank-Switched RAM Areas 


The //c comes with 64K of main RAM memory which is normally used by 
Applesoft and ProDOS. This memory, however, is not mapped to one contig- 
uous area of memory encompassing the entire 64K space that the 65C@2 is 
capable of addressing. The first 48K of this memory space corresponds to the 
contiguous block of memory from $0000 . .. $BFFF but the remaining 16K of 
memory, which is called “bank-switched RAM,’ corresponds to one 8K region 


of memory from $E000...$FFFF and two 4K regions of memory from 
$D000 ... $DFFF. 


The addresses used by bank-switched RAM are exactly the same as those 
used by the Applesoft ROM and the standard system monitor ROM. A memory 
map of the alternative main memory areas from $DQ00 ...$FFFF is shown 


in Figure 8-1. 
STANDARD 
SYSTEM MONITOR 


$FFFF 


$F800 


APPLESOFT 


INTERPRETER 
$EOOO 
(THERE ARE TWO 
$Dx BANKS) 
$D000 
MAIN ROM 
BANK-SWITCHED 
RAM 


Figure 8-1. Alternative main memory areas from $D000... $FFFF. 


The 16K bank-switched RAM on the //c traces its roots to the earlier Apple 
II or Apple II Plus models. On those models, the 16K of bank-switched RAM 
was introduced to the system by inserting a special 16K memory expansion 
card into slot @ of those systems. The original reason for adding this memory 
was to provide needed space for the extremely large Apple Pascal Operating 
System. The extra memory, however, can also be used for conventional data 
and program storage. In fact, ProDOS occupies much of bank-switched RAM. 

The //c reserves several I/O memory locations for use as soft switches to 
control whether bank-switched RAM or the corresponding ROM space is to 
be active. As we will see in the following section, we can even set these switches 
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in such a way that the RAM area will be active for write operations at the 
same time that the corresponding ROM area is active for read operations, or 
so that the RAM area can be read from but not written to. 


Using Bank-Switched RAM 


As we have seen, the 16K of bank-switched main RAM in the //c is made up 
of one 8K area that is mapped to the addresses $E000...$FFFF and two 
different 4K areas that are mapped to the addresses $D000 ... $DFFF. These 
4K areas are commonly referred to as ‘“‘banks.”’ 


Unfortunately, there are two schools of thought on how to refer to these 
two 4K memory banks: sometimes they are referred to as banks @ and 1 and 
sometimes as banks 1 and 2. For our purposes, we will use the latter nomen- 
clature. 


The sixteen I/O addresses in the range $C08@....$C@8F are used as soft 
switches to control the operation of the bank-switched RAM. Switches are 
available to select which of the two 4K banks is to be used, to enable the 
bank-switched RAM for reading, for writing, or for both reading and writing. 
Note that the bank-switched RAM does not have to be enabled for reading 
and writing at the same time. This means that you can be writing to the RAM 
area while running a program that uses subroutines in the ROM that occupies 
the same memory locations (that is, subroutines in Applesoft and the system 
monitor). 


To activate the particular mode of operation that is desired, it is necessary 
to select the appropriate soft switch address and then perform any kind of 
read operation at that address, for example, an LDA, LDY, LDX, or BIT 
instruction in assembly language or a PEEK from Applesoft. 


The addresses that are to be used to control the operation of bank-switched 
RAM are of the form $C08X, where X represents the four least-significant bits 
of the address. Figure 8-2 indicates the general function of each of these bits; 
only three of these bits are used. 


1/O Address: $CO8X 


BANK— READ— WRITE— 
X = SELECT UNUSED SELECT SELECT 
bit 3 bit 2 bit 1 bit @ 
1=bank 1 1 1 —r» read RAM/write RAM 
d=bank 2 4) 1 —r. read ROM/write RAM 
1 Q — » read ROM/write ROM 
") 4) —», read RAM/write ROM 


Figure 8-2. Bank-switched RAM control bits. 
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The functions of each of the three active bits are as follows: 


Bank-Select Bit (bit3). This bit indicates which of the two $D000-$DFFF 
memory banks is to be used. If the bit is set to 1, then bank 1 will be selected; 
if it is cleared to 0, then bank 2 will be selected. 


Read-Select Bit (bit 1). This bit, in conjunction with the write-select 
bit, indicates the read status of bank-switched RAM. If the bit is set equal to 
the value of the write-select bit, then locations in bank-switched RAM will be 
read from when an address in the range $D000 . . . $FFFF is specified; other- 
wise, the corresponding locations in ROM will be used. 


Write-Select Bit (bit 0). This bit indicates the write status of bank- 
switched RAM. If the bit is 1, and the I/O address is read twice in succession, 
then locations in bank-switched RAM will be written to when an address in 
the range $D000 ...$FFFF is specified; otherwise, the corresponding loca- 
tions in ROM will be used. 


There are eight different ways of turning on and off these three control bits, 
and each of the eight different addresses generated controls bank-switched 
RAM in an unique way. The function of each of the eight unique bank-switched 
RAM soft switches is summarized in Table 8-1. 


Table 8-1. Bank-switched RAM soft switches. 


Address Active Read Write 
Hex (Dec) Symbolic Name $Dx Bank From to RAM? 
$CO8O (49280) READBSR2 2 RAM No 
$CO8 1 (49281) WRITEBSR2 2 ROM Yes* 
$CO82 (49282) OFFBSR2 2 ROM No 
$CO83 (49283) RDWRBSR2 2 RAM Yes* 
$CO88 (49288) READBSRI 1 RAM No 
$CO89 (49289) WRITEBSR1 1 ROM Yes* 
$CO8A (49290) OFFBSR1 l ROM No 
$CO8B (49291) RDWRBSRI1 1 RAM Yes* 


A location must be read from to perform the indicated function. 


*Read twice in succession to write-enable bank-switched RAM. 


Reading the Status of Bank-Switched RAM Soft Switches 


Any program that changes the soft switches that control the state of bank- 
switched RAM should properly restore them to their original states when the 
program ends. (If it doesn’t, the next program executed may not perform 
properly.) This can easily be done on the //c because there are two I/O status 
locations, called RDBANK2 ($C@11) and RDLCRAM ($C@12), that can be read 
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to determine the current state of the bank-switched RAM switches. These two 


locations are summarized in Table 8-2. 


Table 8-2. Bank-switched RAM status locations. 


Address 
Hex (Dec) 


$CO11 (49169) 


$CO12 (49170) 


Symbolic Name 
RDBANK2 


RDLCRAM 


Description 


If this location is >=$80, then 
Bank2 of bank-switched RAM has 
been selected; if not, Bank1 has 
been selected. 


If this location is >=$8@, then 
bank-switched RAM has been read- 
enabled; if not, the corresponding 
ROM locations are enabled. 


A program that saves the two bank-switched RAM status values and then 
uses them to restore the original state of bank-switched RAM would look 


something like this: 


LDA 
STA 
LDA 
STA 


[the 


LDA 
BPL 
LDA 
BPL 
LDA 
LDA 
RTS 
SETROM LDA 
LDA 
RTS 
SETBANK1 LDA 
BPL 
LDA 
LDA 
RTS 
SETROM1 LDA 
LDA 
RTS 


RDBANK2 
BANKSAVE 
RDLCRAM 
READSAVE 


e 
? 


e 
? 


Save bank status 


Save read-enable status 


program fiddles with 
bank-switched RAM here] 


BANKSAVE 
SETBANK1 
READSAVE 
SETROM 
$C 083 

$C 083 


$0081 
$C 081 


READSAVE 
SETROM1 
$C08B 
$C88B 


$0089 
$C 089 


° 
? 
a 
? 
® 
? 
® 
? 
e 
? 


« 
? 


a 
? 


a 
? 


e 
? 


ry 
? 


e 
? 


. 
? 


e 
? 


® 
? 


Get bank status 

Branch if bank1 selected 

Get read-enable status 

Branch if ROM selected 

Read RAM, banke 
Cwrite-enable) 


Read ROM, banke 
Cwrite-enable) 


Get read-enable status 

Branch if ROM selected 

Read RAM, bank’ 
Cwrite-enable) 


Read ROM, bankt1 
Cwrite-enable) 
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Since there is no status location available for determining the write-enable 
status of bank-switched RAM, you always have to ‘‘guess” what it was. The 
best guess is that it was write-enabled because even if your guess is wrong, 
no program should be trying to write to bank-switched RAM without first 
write-enabling it anyway. In keeping with this, those soft switches that write- 
enable bank-switched RAM were used in the above example (remember that 
they must be read twice in succession). 


Auxiliary Bank-Switched RAM 


There is another 16K bank-switched RAM area available in the //c’s 64K 
auxiliary memory space. 


The same soft switches that are used to control the main bank-switched 
RAM area are used to control the bank-switched RAM area in auxiliary 
memory. Before you can read to or write from this part of auxiliary memory, 
however, you will also have to use another set of switches that control, among 
other things, which of the two bank-switched RAM areas is to be used. These 
switches are ALTZPOFF ($C008) and ALTZPON ($C0Q9) and are described in 
Table 8-3. The status of the switch is held in ALTZP ($CO16). 


Table 8-3. Auxiliary bank-switched RAM soft switches. 


Address 
Hex (Dec) Symbolic Name Description 
$COQO8 (49160) ALTZPOFF Enable main bank-switched RAM 
+ main zero page/stack 
$C009 (49161) ALTZPON Enable auxiliary bank-switched 
RAM + auxiliary zero page/stack 


$CO16 (49174) ALTZP Status: > = $80 is ON, <$80 is OFF 


The ALTZP switches are used not only to select which of the two bank- 
switched RAM areas is to be used, but also to select which of two 65C@2 zero 
pages ($00 ...$FF) and stacks ($100 ...$1FF) are to be used. As you might 
expect, the //c keeps its ‘spare’ zero page and stack in auxiliary memory and 
the ‘‘original” ones in main memory. This means that as soon as the ALTZPON 
switch is set, the main zero page and stack are disengaged and unless the 
program that is running realizes this and adjusts for it, it might just end up 
in the twilight zone. 


To avoid such problems, the program must always set ALTZPOFF as soon 
as it is finished dealing with auxiliary bank-switched RAM but after it has 
returned from all subroutines that it has called since it first set ALTZPON. 
The return addresses for these subroutines are stored in the auxiliary stack 
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and not the main stack and will be lost when the main stack is restored. For 
similar reasons, the program must never return from a subroutine that was 
called before ALTZPON was set until ALTZPOFF is restored. Furthermore, 
before setting ALTZPON, the program should move to a safe part of memory 
all zero page locations that it will be using while ALTZP is ON. Once ALTZP 
is ON, it can move them into the same locations in the auxiliary zero page. It 
should repeat this process when going in the other direction (that is, from 
ALTZPON to ALTZPOFF) so that no zero page information is lost. 


Playing with Bank-Switched RAM 


If you want to store information (programs or data) in bank-switched RAM, 
then you must first write-enable the portion of bank-switched RAM that you 
want to write to, store the information at the desired locations in the 
$D000 ... $FFFF address space, and then write-protect bank-switched RAM. 
The programming sequence to use to do this would be as follows: 


LDA $C@81 sTwo accesses will write- 
enable 
LDA $C9@81 *Bank-switched RAM Cbank 2) 
Cstore information] 
LDA $C9882 ;sWrite-protect and set 
ROM read 


To read information (programs or data) contained in bank-switched RAM, 
or to execute programs that reside there, you must first enable bank-switched 
RAM for reading, read the information or execute the program, and then re- 
enable reading of the ROMs. The programming sequence would be as follows: 


LDA $C989 sread-enable bank-switched 
RAM Cbank 2) 
Cread information] 


LDA $C982 sre-enable ROM read 


The latter method can be used to execute assembly-language programs 
only. The reason that Applesoft programs cannot be made to execute while 
residing in bank-switched RAM is that the place where the program is stored 
and the Applesoft ROM area must be active at the same time and this just 
isn't possible because bank-switched RAM and the Applesoft interpreter use 
the same addresses. 


Note that if you are running assembly-language programs that reside in 
bank-switched RAM, you must make absolutely sure that those programs do 
not use subroutines contained in the Applesoft or standard system monitor 
ROMs. The reason is simple: as far as the //c is concerned, as soon as you read- 
enable bank-switched RAM, the //c doesn’t think the ROMs exist and so the 
system will “hang” when it attempts to execute a ROM subroutine. If you 
really must use these ROM subroutines, you must first execute a JSR instruc- 
tion to a location in normal RAM that contains code that first deselects bank- 
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switched RAM for reading and selects the ROMs ($C0@82), calls the ROM 
subroutine, and then read-enables bank-switched RAM ($C@8@) and executes 
an RTS instruction to return to the program in bank-switched RAM. 


To avoid these software complexities, you could move the ROM code that 
you need to use into bank-switched RAM by write-enabling bank-switched 
RAM and then performing a memory move from the ROMs to the same 
memory locations in bank-switched RAM. When this is done, the program 
can call the ‘‘pseudo-ROM” locations directly. 


You should bear in mind one more important consideration when using 
bank-switched RAM. Do not attempt to deselect bank-switched RAM for 
reading while running a program that is contained in bank-switched RAM. If 
you try to do this, the motherboard ROMs will immediately be enabled and 
your program, which is still executing at the same address in RAM, will 
suddenly enter limbo because its code has been “replaced” by the internal 
ROM code. Any deselection of bank-switched RAM must be done by a program 
segment that resides in ‘‘normal’ RAM (from $0000... $BFFF). 


Bank-Switched RAM and ProDOS 


If you are using ProDOS then you should not try to use the main bank- 
switched RAM area for data or program storage. The reason for this is simple: 
ProDOS uses this area of memory to hold its operating system subroutines. 
If you overwrite this area, you will almost certainly crash the system. Use the 
bank-switched RAM area in auxiliary memory instead. 


Auxiliary RAM Memory Area 


‘Auxiliary’ memory is an extra 64K memory space which is built into the 
/ic and is mapped to addresses in exactly the same way as main RAM memory. 
As we saw in Chapter 7, 1K of auxiliary memory from $400 ...$7FF is used 
to support the //c’s 8@-column display mode and another 8K from 
$2000 ... $3FFF is used to support the double-width high-resolution graphics 
display mode. In addition, auxiliary memory is used as a special RAMdisk 
volume called /RAM when ProDOS is active. In the following sections, we 
will be describing in detail how to use auxiliary memory. 


There are several soft switches that are used to control auxiliary memory. 
We have already discussed some of these in Chapter 7, when we looked at 
how to control the 80-column text display and double-width graphics dis- 
plays. In addition, in the previous section, we saw that the upper 16K of 
auxiliary memory is functionally identical to main memory’s bank-switched 


RAM and can be selected or deselected by making use of the ALTZPON and 
ALTZPOFF switches. 


8/Memory Management [__| 237 


In this section, we will examine all the other soft switches that control 
auxiliary memory and elaborate further on the ones that have previously been 
discussed. 


Using Auxiliary Memory 


There are three main groups of switches that control the status of auxiliary 
memory. These are the ALTZP switches (‘‘ALTernate Zero Page’), the RAMRD 
(“RAM ReaD”’) switches, and the RAMWRT (‘‘RAM WRiTe’’) switches; they 
are summarized in Table 8-4. 


Table 8-4. Auxiliary memory soft switch and status locations. 


Address 
Hex (Dec) Symbolic Name Description 

$CQ0@2 (49154) RAMRDOFF Read main memory from $200- 
$BFFF 

$CO0O03 (49155) RAMRDON Read aux. memory from $200- 
$BFFF 

$C013 (49171) RAMRD Status: > =$80is ON, <$80 is OFF 

$CO04 (49156) RAMWRTOFF Write main memory from $200- 
$BFFF 

$CO@O@5 (49157) RAMWRTON Write aux. memory from $200- 
$BFFF 

$CO14 (49172) RAMWRT Status: > = $80 is ON, <$80 is OFF 

$COO8 (49160) ALTZPOFF Select main memory from $0-$1FF 


and enable main 16K bank from 
$D000-$FFFF 

$COO09 (49161) ALTZPON Select aux. memory from $0-$1FF 
and enable aux. 16K bank from 
$D000-SFFFF 

$CO16 (49174) ALTZP Status: > =$8@is ON, <$80 is OFF 


The ALTZP Switch 


We briefly discussed ALTZP earlier in this chapter when we looked at the 
bank-switched RAM contained in auxiliary memory. The ALTZP switches 
control two blocks of memory that are duplicated in main and auxiliary 
memory. First, they are used to select whether the 65C@2 zero page and stack 
areas ($0000 ...$@1FF) in main memory or in auxiliary memory are to be 
used. Second, they are used to select whether main bank-switched RAM or 
auxiliary bank-switched RAM is to be used. 


238 [|__| Inside the Apple //c 


The ALTZPON ($C009) switch is used to select auxiliary memory and the 
ALTZPOFF ($C008) switch is used to select main memory. The current status 
of this switch can be determined by reading ALTZP ($C016); if the value read 
from this location is greater than 127, then ALTZP is ON; otherwise it is OFF. 
Note that you must write to the ALTZPON and ALTZPOFF switches in order 


to use them. Figure 8-3 indicates which memory areas are switching whenever 
the ALTZP switches are written to. 


$FFFF 


HIGH-RES 
PAGE1 RAM 


TEXT PAGE1 
RAM 
ote RRA 


MAIN<«>AUXILIARY SWITCHING 
[_]NOT SWITCHING 


Figure 8-3. The effect of switching ALTZP. 


As was mentioned earlier, great care must be taken when using the ALTZP 
switches to ensure that vital zero page and stack information is not “lost.” 
All 65C0@2 operations that affect the stack (this includes PHA, PLA, PHX, PLX, 
PHY, PLY, PHP, PLP, JSR, and RTS instructions) use the stack that is cur- 
rently selected by ALTZP, which is not necessarily the stack in main memory. 
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So, if ALTZP is on and information is stored on the stack in auxiliary memory, 
don’t expect it to be on the stack in main memory when ALTZP is turned off. 


Keep in mind that it is extremely important that the value of the 65C@2 
stack pointer be saved before changing ALTZP and then restored when ALTZP 
is changed to its original state. If this is not done and the stack pointer is 
changed while in the other state, then the program will become hopelessly 
confused and will crash. The following program segment will do the trick: 


TSX ;Put stack pointer in X 
STX SAVESP ; and save it somewhere in memory 
STA ALTZPON ‘Turn on ALTZP 


[execute instructions] 


STA ALTZPOFF -Turn off ALTZP 
LDX SAVESP ;Get original stack pointer in X 
TXS - and restore it 


Any zero page locations that need to be used after ALTZP has been changed 
will have to be duplicated in the other portion of memory before they can be 
properly used. To do this, it is necessary to move the contents of zero page 
into a part of memory that the ALTZP switches do not affect, say $200 .. . $2FF, 
set the appropriate ALTZP switch, and then move this area of memory back 
down into the new zero page. This process should be repeated when setting 
ALTZP back to its original position. 


The RAMRD and RAMWRT Switches 


The RAMRD switches are used to control whether read operations are to 
use the memory locations from $200 ... $BFFF in main memory or the same 
locations in auxiliary memory. The RAMWRT switches control write oper- 
ations for the same area of memory. 


If RAMRDON ($C003) or RAMWRTON ($C@Q5) is selected, and the 
8Q0STOREOFF ($C@00) switch is active, then the entire block of auxiliary 
memory from $200... $BFFF will be selected for reading or writing, respec- 
tively. If RAMRDOFF ($C002) or RAMWRTOFF ($C004) is selected, then main 
memory will be selected for reading or writing, respectively, instead. The 
memory areas that are switched by RAMRD or RAMWRT in each of three 
different situations are summarized in Figure 8-4. 


The area of memory that is affected when the RAMRD and RAMWRT 
switches are used is slightly different if the switching occurs when 80STOREON 
($C@O1) is active. As you will recall from Chapter 7, the 80STORE switches 
are used to define the effect of the //c’s PAGE2 switches. If 80STORE is ON, 
then PAGE20N ($C@55) and PAGE2OFF ($C@54) are used to select whether 
the text screen video RAM page ($400 . . . $7FF) in auxiliary or main memory 
is to be selected. In addition, if HIRESON ($CQ57) is active, then the PAGE2 
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Figure 8-4. The effect of switching RAMWRT or RAMRD. 


switches will also select whether the high-resolution graphics screen video 
RAM page ($2000 .. . $3FFF) in auxiliary or main memory is to be selected. 
The important point to note is that whenever 80STORE is ON, the PAGE2 
switches take priority over the RAMRD and RAMWRT switches and so these 
latter two switches cannot be used to control which of the video RAM areas 
are active. The effect of switching PAGE2 with 80STOREON is summarized 
in Figure 8-5. 
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Figure 8-5. The effect of switching PAGE2. 


Auxiliary Memory Support Subroutines 
The //c has two useful subroutines contained in its system monitor ROM 


area that facilitate the use of auxiliary memory. These subroutines are called 
AUXMOVE ($C311) and XFER ($C314). 


AUXMOVE ($C311)—Transferring data to and from auxiliary 
memory 


AUXMOVE is used to transfer blocks of data contained within the memory 
range $200 ... $BFFF from main memory to auxiliary memory or vice versa. 
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Before using this subroutine, six locations in zero page must be set so that 
they hold the parameters of the block move. These are summarized in Figure 
8-6. 


The beginning address of the block to be moved must be stored at locations 
A1L ($3C) and A1H ($3D) and the ending address at A2L ($3E) and A2H ($3F). 
Finally, the destination address must be stored at A4L ($42) and A4H ($43). 
As is usually the case on the //c, the low-order part of each address is stored 
in the first byte of each zero-page pair. 


The state of the 65C@2 carry flag is used to tell AUXMOVE the direction of 
the block move. If the carry flag is set, then the move will be performed from 
main memory to auxiliary memory. If it is clear, the move will take place in 
the opposite direction. The state of the carry flag can be set by using the 
65C02’s CLC (clear carry) and SEC (set carry) instructions. There is no simple 
way, however, of setting these flags using Applesoft commands; the best that 
can be done is to call a short machine-language subroutine that clears or sets 
the carry flag before calling AUXMOVE. 


Source Block —_—_—_—___ > Destination Block 


| A1L/A1H A2L/A2H A4L/A4H 
($3C/$3D) ($3E/$3F) ($42/$43) 


Carry Flag Set (1) Move from Main to Auxiliary memory 
Carry Flag Clear (®@): Move from Auxiliary to Main memory 


Figure 8-6. AUXMOVE ($C311) subroutine parameters. 


The Applesoft program in Table 8-5 shows how you might transfer an area 
of memory between main and auxiliary memory. It saves a main-memory 
high-resolution graphics screen to auxiliary memory and then brings it back 
again. 


The program first installs a short four-byte machine-language program 
beginning at location 768 ($300) by POKEing into memory those DATA state- 
ment values that appear in lines 120 and 130. These values define the following 
simple program: 


SEC 
JMP AUXMOVE 


The program then turns on high-resolution graphics and draws a diagonal 
line on it before setting up the parameters for the block move. In this case, 
the area of memory to be moved is $2000... $3FFF and it will be moved to 
the area beginning at $4000 in auxiliary memory. (You shouldn't try to move 
it to $2000 ... $3FFF in auxiliary memory because if the 80STORE switch is 
ON—and it will be if the 80-column firmware is being used—and high-reso- 
lution graphics are being displayed, then the RAMRD and RAMWRT switches 
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Table 8-5. AUXMOVE—a program to demonstrate how to move 
data between main and auxiliary memory. 


@ REM “AUXMOVE" 

168 PRINT CHR$ €4);"PR#3" 

118 FOR 1 = 768 TO 771: READ X: 
POKE I,X: NEXT 

128 DATA 56: REM "SEC" 

138 DATA 76,17,195: REM “JMP $C 
311" 

148 HGR : HCOLOR= 3: HPLOT 16,1 
9 TO 158,158 

158 HOME : VTAB 22: PRINT TABC 
17);"MAIN <---> AUXILIARY ME 
MORY TRANSFER DEMO" 

16@ HTAB 2: VTAB 23 

178 PRINT “PRESS ANY KEY TO SAV 


—E THE SCREEN IN AUXMEM: "s: GET 
A$ 

188 REM SET UP THE PARAMETERS O 
F THE MOVE: 

198 POQKE 68,0: POKE 61,32: REM 
FROM $2008 


206 POKE 62,255: POKE 63,63: REM 
THROUGH $3FFF 

218 POKE 66,08: POKE 67,64: REM 
TO $4809 CAUX) 

220 CALL 768: REM PERFORM THE M 
OVE 

230 HTAB 2: VTAB 23: CALL - 95 
8 


2406 PRINT “PRESS ANY KEY TO CLE 
AR THE SCREEN: "3: GET A$: HGR 

2S5S@ HTAB 2: VTAB 23: CALL - 95 
8 

268 PRINT “PRESS ANY KEY TO RES 
TORE THE SCREEN FROM AUXMEM: 


me. :s GET A$ 

27@ POKE 768,24: REM PUT IN A “" 
CLC" 

286 REM SET UP THE PARAMETERS O 
F THE MOVE: 

2980 POKE 68,0: POKE 61,64: REM 
FROM $4000 


308 POKE 62,255: POKE 63,95: REM 
THROUGH $SFFF 

310 POKE 66,8: POKE 67,32: REM 
TO $2000 CMAIN)D 

320 CALL 768: REM PERFORM THE M 
OVE 
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that AUXMOVE uses when performing the transfer will not affect this area 
of memory and no transfer will take place.) 


After the screen has been saved to auxiliary memory, you can press a key 
to clear the screen, and then press another key to restore the line that was 
drawn on the screen. The line is restored by simply moving the 8K of screen 
memory that was saved in auxiliary memory back into main memory and 
not by redrawing the line. 


To transfer a block of memory in the opposite direction, the first instruction 
in the four-byte machine-language subroutine must be changed from SEC to 
CLC. This is done in line 270 by POKEing 24 into location 768. The number 
24 is the value of the CLC instruction. 


XFER ($C314)—Transferring control to a program from main or 
auxiliary memory 


XFER is used to transfer control to a program in either main or auxiliary 
memory and, at the same time, to select which stack and zero page is to be 
used when the new program takes over. This is done by setting up certain 
parameters and executing a JMP (jump) instruction to XFER at $C314. 


As with AUXMOVE, certain parameters and 65C@2 flags must be set up 
before XFER is called. These are summarized in Table 8-6. First of all, the 
address of the program that is going to take control must be placed at locations 
$3ED and $3EE (low-order byte first). Then, the carry flag must be adjusted 
to indicate the direction of transfer: it must be set (1) if control is being 
transferred from a program in main memory to a program in auxiliary mem- 
ory and clear (@) if transferring control in the reverse direction. Finally, the 
65C@2 overflow flag must be adjusted to indicate which of the two zero pages 
and stacks the new program is to use: if it is set (1), then the auxiliary zero 
page and stack will be used and if it is clear (®), then the main zero page and 
stack will be used. 


Table 8-6. XFER ($C314) subroutine parameters. 


Parameter Description 
Transfer address $3ED/$3EE (low-order byte first). This contains the 


starting address of the program to which control is 
to be transferred. 


Carry flag Carry set (1) means “‘transfer from main to auxiliary 
memory.’ Carry clear (@) means “transfer from aux- 
iliary to main memory.’ 


Overflow flag Overflow set (1) means “use auxiliary stack and zero 
page. Overflow clear (@) means ‘‘use main stack and 
zero page. 
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The CLV (clear overflow) instruction can be used to clear the 65CQ2 overflow 
flag to zero. There is no similar command, however, that can be used to set 
the overflow flag to one. One method of forcing the overflow flag to one is to 
use the BIT instruction to test any memory location that holds a byte that 
has a ‘‘1”’ in bit 6. A convenient location to use is $FF58 because there is an 
RTS instruction located there and it has an opcode value of $60. 


Of course, before you transfer control to a program in the other memory 
area, you had better make sure that the program has been loaded there. This 
is easily done for programs residing in main memory but is a bit more tricky 
for those residing in auxiliary memory. The easiest way to load a program 
into auxiliary memory is to use the AUXMOVE subroutine. 


Note that the same concerns that were raised about the stack and the stack 
pointer when discussing the ALTZP switches apply to the use of XFER. It is 
good practice to save the stack pointer immediately before jumping to XFER 
and then to restore it if and when a reverse transfer is made. In addition, if 
the two programs are both using the same stack, care must be taken to avoid 
overwriting any information that the other program has left on the stack. 
This is most easily done by saving the whole stack when control is transferred 
and then restoring it just before returning to the calling program. Alterna- 
tively, the two programs should each use a different stack; however, this 
cannot be done without using two zero pages as well and this may be incon- 
venient. 


Running Co-Resident Programs 


As we have seen, the 64K of auxiliary RAM memory is virtually a mirror 
image of the 64K of main RAM memory. Both of these memory spaces span 
exactly the same logical addresses, each has its own 65C@2 stack and zero 
page, and each has a 16K area of bank-switched RAM. One important area of 
difference, however, lies in the use of locations $400 ...$7FF. When in 4@- 
column text mode, only these locations in main memory are used to define 
the video display; the same locations in auxiliary memory have no effect on 
the video display. When the 80-column display is active, locations $400 ... $7FF 
in main memory define the odd-numbered columns in the display while the 
same locations in auxiliary memory define the even-numbered columns. 


The similarities between these two 64K spaces are great enough, however, 
that it is conceivable that different programs could be loaded into each space 
and then run independently of one another (well, almost independently of 
one another). After all, since each program can have its own stack and zero 
page, there is not a strong temptation for either program to interfere with the 
other’s use of these important areas of memory. The video display will have 
to be shared, however, for the reasons just given. 


The CONCURRENT program in Table 8-7 is a short assembly-language 
program that allows you to run one of two Applesoft programs that can be 


246 [___] Inside the Apple //c 


CL SS9T) 1$0SaTddy 0} 3y4PYS PTODS L-9903$ NO3 LAOS Idd¥ GE 
62 

BuTy~Nouqns sAOW NIYW <--> XN: LLEIS$ NOI SBAOQWXNG 82 

Le 

O@8$=< $1 UO F5NZOYS qZ1 14: 9109%$ nda dZ11V 92 
yore}s+a6ed ovaz Avert txne yoaTas! 6009$ N03 NOdzZ110~ Sz 
yoe1S+a6ed ovaz utew yoatas: 8489¢$ N03 440dZ211V bd 

E? 

didag*''@a72g wouy Avett Ixne azytums S8#89$ NOI NOLAMWYVSA c7d 
J45G$°°'OBS$ WOUy UTEW ByTum: bO00$ NOS JOLAMWYS L2 
disag’''@azg wouy Aueryttxne peay: €909$ ndo3 NOddWva A 
4450S °° GOSH WOUY UTeW Pedy: 2890$ N03 ASOdAWVA 61 
44Z$° °° OOS YOVTMS 1,uU0G5 L9@89$ NOAA NOSB8aAOLS 8 | 
sSayoytms Auowap « Ly 

91 

cbs NOI pV St 

JE$ NDIA rAy) bi 

JES NDGA LY E 1 

SJAOWXNY 4Os SUOTYTEOOT vayaweued « 24 

LL 

9S9E$ NDI MSO G1 

6 

cATuo *xneB) MSO ¢O ANTeEA TeT{TUY: Z$¢ noz ms9a10 8 
Paue anes svayutod 19e4S; 9¢ NDZ 3JAUSdS L 

9 

CASTp wou} weuBoud styy NNaa) « g 

> 

HRHEHHEEHREHHRERHESRSD e 

* IN3YSNONOO + FA 

RHREHEHEHRHEEEE HH L 


*ALOWIOU ATVTIXNe 
pue uleur ul surer301d yyosajddy usemjaq SUIYyd}IMS MOTTE 07 WIeIZOId E—TNAYANINOD ‘L-8 F421 


[| 247 


8 / Memory Management 


(penul}uo5) MS) 


V0) 


~NOJAOLSGS daay 01 yUTT yndyno auTyapay « 


UdauoS AY} IWeaTQ: 3WOH 

yndut uwnyToo-gp Pyepuejys sO} 49S: GaxL3as 
yndyno UWNTOI-Hp PHYBPUEYS AWOF 19S5 QIALIS 
apow 4xXa} Usa voS-TTN} 19S: LINI 

OapTA TeBwuou jas: WAONLSS 


saGesn abed-ouaz Auet{Ttxne §,4vo},TUOW 3y4 
yoeys + a6ed ovaz *xne yoaTAaS: NOdZL 719 


JAOWXNY 
(waw *xXNeB Of SAOW): 
L+oU 
LSV IMS <# 
oV 
LSYIMS># 
L+bU 
L+1 
HOLIMS<# 
bY 
LY 


HOLIMS># 
>sAuowaw AuetTtTxne oO} 


CaCS 


6844$ 
E644$ 
b834$ 
B8S904$ 


Ic 4$ 
>SOUTTNOYGNS UOT LEZTTSET} 


ase 
ase 
ase 
ast 
ase 
qd19 


SZTTSETYIUL « 


V1LS 


asf 
J3S 
VLS 
vd] 
WLS 
V0] 
VLS 
WLS 
0d] 
VLS 
VLS 
vd] 


HOLIMS Adog « 


9a0 


ADS 
Noa 
NOS 
No3 


Nos 
TUT 


GaAlss 
QIALIS 
WAONLSAS 
4IWOH 
LINI 


AOTTUOL) + 


99 
S9 
bg 
Eg 
79 
Lg 
99 
65 
8S 
ZS 
9S 
SS 
bS 
ES 
eS 
LS 
8S 
6b 
8b 
Lb 
9b 
SP 
bb 
Ev 
ob 
Lb 
Ob 
6E 
BE 
LE 
9E 
SE 
be 
EE 
cf 


Jd 
44 
434 
q4 
4d 


89 


0) 


9E 


85 
68 
€6 
d¢é 
b8 


69 


LL 


JE 
EO 
JE 
Vb 
Eb 
d€ 
EO 
op 
JE 
00 


SV 


Oe 
O¢ 
Oe 
Oe 
2 
8d 


qs 


Oe 
8E 
S8 
6Y 
S8 
6V 
S58 
S58 
6Y 
$8 
S8 
6Y 


248 [| Inside the Apple //c 


WHa OBPTA YoyTMS 4,uU0q5 


S ‘d ‘wv ‘A SX BaeBs: 
:UTeW pue *“xXNe UsaMyag 


yoe1s + a6ed ovaz utew yoaTaS$ 


Auowaw *‘xne ut 4T anes pue $ 
yJayutod y9e1s Tetytut dn yas 
Auowaw Auety~txne svayua noA ¢$ 
SWT1 TSuty ayy yyosatddy : 
yoy yutod Aujyua yueys $ 

PTOO ay} OF UUNjau eB dn jas 


syoe7s Auowaw Averttxne 


NO@8dOLS 
JAVSdS 


3JAVSd 


JAVSY 


JAVSA 
AAVSX 


VLS 
X1S 
XSL 
V1LS 
V1d 
dHd 
VLS 
ALS 
XLS 


HOLIMS 


SAOW O} PSSN ST'HOLIMS «* 


440d211¥ 


3AVSdS 
Cjigs# 

s5l$ 
LjIOS lddV># 
J3Atb$ 

LAOS IlddV<# 


L+MSO 
LONOMIN<# 
MSO 
LNOMAN># 


b+MSO0 10 
L+MS9 
MSIA 10 


sid 


V1LS 


XLS 
X01 
V1LS 
vd] 
VLS 
Vd) 


aZTTetytuy 


VLS 
va ¢ 
VLS 
Vd) 


V1LS 
Vd) 
VLS 


* 


L6 
96 
S56 
bG 
a) 
76 
LG 
06 
68 
88 
£8 
98 
58 
b8 
€8 
c8 
L8 
68 
62 
BL 
LL 
92 
SZ 
bL 
EL 
od 
LZ 
OL 
69 
83 
L9 


89 


EB 


EO 
EO 
EO 


Re) 


L@ 


L@ 


L@ 
99 


Ev 


Ov 
ob 
LP 


88 


90 
d4 
44 
44 
43 
4d 


LE 
EO 
9E 
bb 


88 
LE 
LO 


a8 
98 
a | 
ds 
89 
88 
ds 
J8 
48 


09 


ds 


98 
oV 
ds 
6V 
ds 
6 


58 
ov 
S58 
6Y 


$8 
SY 
$8 


-LLE® 
-4IOED 
-I9ED 
“EGER 
‘UBER 
“60E8 
*9BE8 
“EGER 
*O80E0 


-44cd 
-J41c8 


*Y4c0 
*84¢c0 
*S4c0 
“€4c8 
*84¢0 
-43¢c8 


-J4¢9 
“VAC 
-84¢90 
*94¢0 


>bjcd 
-cd4¢8 
-94¢8 


‘(panuyuod) Atowsuw Areyixne 
pue uyeur uy surexs0id yyosajddy usamjaq SuryoyIMs MOTE 0} wies01d e—LNANANINOOD “L°8 F421 


[| | 249 


8 / Memory Management 


eee eee ee _ __—_—e— 


% 


CMSO0G 10) 
NO#8a0Lls 


Noa 


dW 
VLS 


LSVIMS 


LAOQMAN 


-(Agowaw urew ut) WHY C@PTA uwNTOo-gp ayy Gurtsn « 


wou, Avowaw Avert ttxne ut weuboud ayy Guryuanaud pue 
440ax0LSe@g Gutusny snyy ‘gGG0$ OF SAytYM YT ‘paztyperytut 
ST 1posatddy uaym ‘paztTetT}yIUT ySuty St yyosatddy uaym 
Ajuo papaau ATTeau st auTynouqns yndut mau BHutmoytyTos ayy 


- Tre 


Ad0LS3a 

JOLAMWVA 

Auowaw utew uo usny{t AJOGAWVA 
YORPS+qZ utTew uo uunys 44d0dZ2179 
IAVSY 

IAVSd 

SAVYSA 

AAVSX 

SuaystGau [TTS ayuojysay: JAYSdS 
NOLAMWVSA 

Auowaw *xne uo uyny$ NOGSWYA 
YOVYTS+qZ “XMS uo UNL: NOdZ171¥V 
"xNB UT $T UTEW OF OO! NIVWOL 


snyeqys dZiqy 429y49: dZ21 1 


Sd 
oq 
sq 
sd 


dWf 
VLS 
VIS 
VLS 
Silda 
dld 
vd) 
VHd 
V0) 
AQ] 
Xd] 
SXL 
Xd 
VLS 
VLS 
VLS 
IWd 
vd 


* * kK * 


JAVSd 
JAVSA 
AAVSX 
JAVSY 


NIVWOL 


4Jd0LS4da 


98 248 99 
80 18 a8 
EG ce IP 
69 bO C8 
89 ¢8 G8 
89 88 d8 
89 

8¢ 

EB Ob AV 
8b 

EB Eb dV 
EB ob OV 
EB Lb AV 
V6 

98 3Y 

09 S88 U8 
9) €8 d8 
89 68 d8 
Gl Bt 

69 QL dV 


“Lpeo 
“boED 


250 [___| Inside the Apple //c 


loaded into memory at the same time, one in main memory and the other in 
auxiliary memory, and to easily switch between the two programs. It must 
be activated by using the BRUN command to load and execute it directly 
from diskette; you must be in standard 40-column mode before doing this. 


The first thing that CONCURRENT does is to copy its SWITCH and NEWOUT 
subroutines from main to auxiliary memory by using the AUXMOVE subrou- 
tine. The SWITCH subroutine is responsible for transferring control from 
main to auxiliary memory and vice versa, and so a copy of it must be stored 
in both these memory areas to ensure that it is always available. There is one 
other important reason for duplicating SWITCH in this way. Part way through 
the subroutine, the area of memory (main or auxiliary) that is currently active 
will be turned off and replaced by the other, thus causing the current copy of 
SWITCH to temporarily vanish. This would normally cause the system to 
hang because the instruction at the next address at which SWITCH resumes 
executing after switching would no longer be available and the program 
would behave unpredictably. If SWITCH is present at exactly the same loca- 
tions in the other area of memory, however, then one copy will always be 
active and no problems will be encountered. 


After CONCURRENT has moved SWITCH to auxiliary memory, it enables 
the zero page and stack in auxiliary memory (ALTZPON) and then calls five 
system monitor initialization routines (SETNORM, INIT, SETVID, SETKBD, 
and HOME) that will cause the auxiliary zero page to be properly initialized 
so that system monitor I/O subroutines will work properly. 


The next task that CONCURRENT performs is to redefine the standard 
character output subroutine by storing the address of the NEWOUT subrou- 
tine at the CSWL/CSWH ($36/$37) output link in auxiliary memory. The 
NEWOUT subroutine must be used to handle output because of a complica- 
tion that arises when Applesoft is first initialized in auxiliary memory. 


When Applesoft is first initialized, it determines how much RAM memory 
is installed in the //c by storing and reading numbers at the first location of 
each memory page (beginning with page $08) until it finds that the number 
read is not the same as the number stored. When such a discrepancy occurs, 
then a non-RAM location must have been reached. 


On the //c, the first non-RAM address written to will be $C000, which is the 
first address in the //c’s I/O memory space. Unfortunately, this has the side 
effect of turning off the 80STORE soft switch that resides at that location. 
This means that if the RAMRD and RAMWRT switches are on (that is, aux- 
iliary memory from $200...$3FF and $800 ...$BFFF is active), then the 
auxiliary memory space from $400 .. . $7FF will be active as well. (Remember 
that this same space in main memory—which represents the video RAM for 
the 40-column text screen—will remain active if 80STORE is on.) This aux- 
iliary memory space has no effect on the 40-column screen display, however, 
and so the screen display will not change when attempts are made to update 
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it by calling the standard video subroutines (that only affect the currently 
active $400 ... $7FF space). 


If we could turn the 80STORE switch on before Applesoft tries to perform 
its frst video operation after initialization (the displaying of its “]’’ prompt 
symbol), then we could avoid the problem of having the “wrong” $400 . . . $7FF 
space active. This is done by replacing the standard output subroutine with 
the nearly identical NEWOUT subroutine. In fact, the only difference is that 
NEWOUT first writes to 80STOREON ($C0@1) to ensure that the video RAM 
area from $400 ...$7FF in main memory will be active. 


Initialization of the Auxiliary Stack 


After the new output link address is set up in auxiliary memory, CONCUR- 
RENT initializes the auxiliary stack by placing the address, less 1, of the cold 
start entry point to Applesoft ($E0Q@) at the first two stack locations, $1 FF 
and $1FE. The high-order part of this address is stored at $1FF and the low- 
order part at $1FE. After this has been done, the value $FD is stored at 
SPSAVE, a temporary storage location. The first time that auxiliary memory 
is enabled by calling SWITCH, the 65C@2 stack pointer register will be loaded 
from SPSAVE, meaning that when the RTS is executed at the end of the 
SWITCH subroutine, control will be returned to $E0@00, the Applesoft cold 
start entry point. The subroutine at $E000 takes care of initializing Applesoft 
in auxiliary memory by setting up all its program and data pointers that are 
contained in zero page. 


The last thing that CONCURRENT does is re-enable zero page and the stack 
in main memory and then end. At this point the //c is configured in such a 
way as to allow you to easily switch between programs in main and auxiliary 
memory. 


Using CONCURRENT 


CONCURRENT is simple to use. Whenever you want to leave main memory 
and resume running the program in auxiliary memory, or vice versa, you 
must activate the SWITCH subroutine by entering a CALL 768 command. 
This subroutine determines which bank of memory is active (by examining 
the status of the ALTZP switch) and then enables the other bank of memory 
from $0000 ...$BFFF (except for the $400...$7FF video RAM area) for 
reading and writing by adjusting the ALTZP,. RAMRD, and RAMWRT switches 
accordingly. The $400 . .. $7FF video RAM area in main memory is kept active 
by writing to 80STOREON ($C001) before accessing the RAMRD and RAMWRT 
switches. 


When the SWITCH subroutine ends, it executes an RTS instruction that 
instructs the 65C@2 to return to the address (plus 1) that is stored on the top 
of the stack. Unless some tricky programming is done, this address is that of 
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the instruction immediately following the JSR instruction that called the 
subroutine. Such is not the case, however, when calling SWITCH because just 
before its RTS instruction is executed, the other stack is reactivated and its 
stack pointer is set equal to the value it had when SWITCH was last called. 
What this means is that as soon as SWITCH is called, the //c begins executing 
those instructions right after the CALL 768 that activated the switch in the 
first place. 


To see a simple example of how CONCURRENT works, first install SWITCH 
by executing CONCURRENT. Then enter the following Applesoft program: 


1080 IF PEEK €49152) = 155 THEN 
POKE 49168,0: CALL 768 
288 PRINT “MAIN MEMORY”: GOTO 108 


and RUN it. This program doesn't do much but continuously print out “MAIN 
MEMORY’ on the screen. However, the program is constantly monitoring 
the keyboard for an ESC character in line 100. If ESC is pressed, then the 
keyboard strobe is cleared (POKE 49168,0) and then SWITCH is called by 
executing a CALL 768 command. 


When SWITCH is called for the first time, you will be put into Applesoft 


direct mode in auxiliary memory. While you are there for the first time, enter 
this program: 


1808 IF PEEK €49152) = 155 THEN 
POKE 49168,@: CALL 768 
200 PRINT “AUXILIARY MEMORY": GOTO 168 


This is the same as the previous program, except that it prints out “AUX- 
ILIARY MEMORY.” Now type RUN to start this program and then press the 
ESC key. As soon as ESC is pressed, you will switch back to main memory 
and the program there will resume executing right where it left off and will 
start printing “MAIN MEMORY.” By pressing ESC again and again, you can 
see that you are indeed switching between the two programs! 


Limitations of CONCURRENT 


The major limitation of CONCURRENT is that the program running in 
auxiliary memory cannot use any ProDOS commands. Although a copy of 
ProDOS could be transferred to auxiliary memory and used by the program 
running there, several problems could arise that would be difficult to solve 
in software. For example, special “lockout” flags would have to be used to 
prevent one program from modifying a file until the other had finished using 
it. If this was not done, then the data in the file could easily become scrambled. 
Rather than complicate the CONCURRENT program and obscure its useful- 
ness as an example of how to use main and auxiliary memory, no attempt 
has been made to allow the program in auxiliary memory to use ProDOS. 


Other problems arise because the two programs must share the same video 
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screen. This means that information placed on the screen by one program 
could easily be overwritten by the other. One solution to this problem is to 
define nonoverlapping text windows for each program by modifying the win- 
dow parameters held in zero page. (See Chapter 7.) 


Since auxiliary memory is initialized by installing the standard 40-column 
input and output subroutines (by calling SETVID and SETKBD), you should 
not enter auxiliary memory when 8@-column mode is active. If you wish to 
use CONCURRENT with an 80-column display, the “JSR SETVID” and “JSR 
SETKBD” instructions should be replaced by a “JSR $C3Q00” instruction; the 
latter instruction takes care of installing the I/O subroutines that support the 
80-column display. Alternatively, you can simply turn 80-column mode on 
by entering PR#3 after installing CONCURRENT. 


Finally, you should note that you must not write to 80STOREOFF ($C000) 
while in auxiliary memory. If this is done, then the auxiliary memory space 
from $400... $7FF will become active and, as explained above, you will not 
be able to display anything on the video screen. 


Further Reading for Chapter 8 


Standard reference works ... 


80-Column Text Card Manual, Apple Computer, Inc., 1982. 
Extended 80-Column Text Card Supplement, Apple Computer, Inc., 1982. 


Note: the above two reference manuals are written for the optional 80- 
column text card used on the Apple //e only. However, much of the 
information in them is directly applicable to the built-in 80-column dis- 
play on the //c as well. 


On uses for auxiliary memory ... 


D.C. Johnson, “Using Auxiliary Memory in the //e’’, Apple Assembly Line, 


August 1983, pp. 2-12. Another program to switch between main and 
auxiliary memory. 


The Speaker 


In this chapter, we will examine another built-in I/O device that the //c 
supports: the speaker. 


The //c’s speaker can be used to add the dimension of sound to programs. 
In many cases, this simply means that you will hear a short (but suitably 
aggravating) beep whenever you make an error. However, some programs, 
notably educational software and games, exercise the speaker in much more 
dramatic ways to generate complex sound effects and recognizable musical 
patterns that tend to dramatically liven up these types of programs. We will 
look at the techniques used to generate music later in this chapter. 


You can make the //c’s speaker beep at you by entering or printing the ASCII 
“bell” character (ASCII code 7). This can be done by pressing [control-G] on 
the keyboard or by printing CHR$(7) from Applesoft. (If you don’t hear any- 
thing, turn up the volume by adjusting the control wheel on the left side of 
the //c). With appropriate software, the speaker can also be used to generate 
music and sound effects and even to reproduce (though crudely) the human 
voice. 


The sounds that the speaker generates are caused by the in and out move- 
ment of the speaker cone; the frequency (also called the pitch) of a sound is 
the same as the frequency of the cone’s movement. The position of the cone 
is controlled by a voice coil and a permanent magnet located near the base 
of the cone. When this coil is turned on, the cone moves out and when it is 
turned off, the cone moves in. Thus, you can select the frequency of the tone 
to be emitted merely by switching this coil on and off at the desired frequency. 


There is one special I/O memory location reserved for the speaker that 
allows you to control it in this way. As indicated in Table 9-1, this is SPEAKER 
($C030). This is yet another soft switch location; each time that it is read 
(using Applesoft’s PEEK or an assembler’s LDA) the state of the speaker 
changes from off to on (if it was last off) or from on to off (if it was last on). 


Generating Musical Notes 


Let's take a close look at how you can use the //c to generate musical notes. 
First, recognize that the sound wave generated by a single musical note is 


255 
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Table 9-1. Speaker I/O memory location. 


Address 
Hex (dec) Symbolic Name Description 
$CO30 (49200) SPEAKER Speaker output. Reading this 
location toggles the state of the 
speaker. 


merely a smoothly varying sine wave, as shown in Figure 9-1 (a). Since, 
however, we can only turn the //c’s speaker on or off (that is, we cannot 
smoothly vary the amplitude of its output), we can only generate square 
waves like the one shown in Figure 9-1 (b). For most frequencies, however, 
this square wave is an acceptable approximation of its sine wave equivalent 
and the sound that is generated is close to what you would normally expect 
to hear. 


(a) Sine wave for pure tone. 


, 


Amplitude 

Time» 
(b) Square wave approximation of pure tone. 
Amplitude 

Time > 


Figure 9-1. Sine waves and square waves. 


Before a specific note can be generated, you will have to know its frequency 
(or “pitch’’). Table 9-2 contains a list of two octaves of musical notes from 
Low “‘C” through Middle “C”’ to High “C’’, their frequencies on the standard 
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Even-Tempered Scale in hertz (cycles/second), and their periods. The period 
is equal to the time it takes to finish one complete sinusoidal cycle and is 


equal to the reciprocal of the frequency. 


To generate the waveform for any note, the speaker must be turned on for 
one-half of its period and off for the other half. Given this information, the 


procedure to follow for generating a note is as follows: 


@ Turn the speaker on 


Wait one-half period 
Turn the speaker off 
Wait one-half period 
Return to step 1 


Table 9-2. Frequencies and periods of musical notes on the even- 


tempered scale. 
Note 


C (Low “C”) 
C# 
D 
D# 
E 
F 
FF 
G 
G# 
A 
A# 
B 
C (Middle “C”) 
C# 
D 
D# 
E 
F 
FH 
G 
G# 


A (Concert “‘A’’) 


A# 
B 
C (High “C”) 


*See text. 


Frequency (Hz) 


131 
139 
147 
156 
165 
175 
185 
196 
208 
220 
233 
247 
262 
277 
294 
311 
330 
349 
370 
392 
415 
440 
466 
494 
523 


Period (psec) 


7,634 
7,194 
6,803 
6,410 
6,061 
5,714 
5,405 
5,102 
4,808 
4,545 
4,292 
4,049 
3,817 
3,610 
3,401 
3,215 
3,030 
2,865 
2,703 
2,551 
2,410 
2,273 
2,146 
2,024 
1,912 


HALFTIME“ 


112 
106 
100 
94 
89 
84 
719 
75 
71 
67 
63 
60 
56 
53 
50 
47 
45 
42 
40 
38 
35 
33 
32 
30 
28 
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Since the status of the speaker toggles between on and off every time you 
access its soft switch at SPEAKER ($C030), you can simplify this flowchart 
by removing steps 3 and 4. 


The above procedure must be repeated for the duration of the note; if you 
are playing a note from a piece of music, this duration will depend on the 
type of note that is being played (a whole note, half-note, quarter-note, and 
so on) and the tempo of the music. 


Table 9-3 shows the NOTE program that uses the //c’s speaker to produce 
a note of a specified frequency and duration. This program toggles the speaker 
whenever the X register, which at the beginning of every tone cycle contains 
a code number related to the period of the note, is reduced to zero by successive 
DEX instructions. The X register is reduced by one unit every 34* HALFTIME 
microseconds, where HALFTIME is this code number and 34 happens to be 
the length of an internal software delay loop that has been used. The code 
number is simply equal to the number of 34-microsecond loops that must be 
performed before one-half of the period of the note elapses. It can be calculated 
by dividing one-half of the period time (in microseconds) by 34. For example, 
the value of HALFTIME for an “A” note (440 Hz) would be equal to 1136 (one- 
half its period in microseconds) divided by 34, which is equal to 33. In this 
way, you can easily calculate the HALFTIME values for all the other notes 
that you may wish to generate; they are listed in Table 9-2 for your conve- 
nience. 


NOTE also allows you to specify the duration of the note to be played by 
adjusting the LENGTH constant. A temporary value of LENGTH, called 
LTEMP, is decremented each time the program executes 255 of the afore- 
mentioned 34-microsecond loops, that is, once every 8670 microseconds. Thus, 
to play a note for one second (1,000,000 microseconds), LENGTH would be 
set equal to 1,000,000/86790, or 115. 


The loop time in the NOTE program has been calculated by determining 
exactly how many 65C@2 machine cycles take place between successive reduc- 
tions of the loop counters (that control the frequency and duration of the note) 
and multiplying that number by the period of the 65C@2 microprocessor’s 
clock. Since the //c’s clock is operating at about 1 MHz, it turns out that the 
loop time (in microseconds) is simply equal to the number of machine cycles 
needed to perform the instructions in the loop. To calculate the total number 
of machine cycles being performed in the loop, you must first determine what 
instructions are being executed in the loop and then add up their individual 
cycle times. The cycle times for each 65C0@2 instruction are listed in Appendix 
II. Note that the number of cycles depends not only on the particular instruc- 
tion being executed but also on the addressing mode that is being used by 
that instruction. 


It should be obvious by now that because of the meticulous timing loops 
that music programs require to produce precise frequencies, it is really not 
possible to create quality music by directly accessing SPEAKER ($C030) using 
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the Applesoft PEEK statement and FOR/NEXT logps. Applesoft delay times 
simply cannot be adjusted as finely as can assembler delay times and, even if 
they could be, they could actually change depending on the location of the 
loop in the program. So stick to assembly language if you want to create 
music. Applesoft programs can be used, however, to POKE frequency and 
duration information into an assembly-language program’s data area and to 
CALL the assembly-language program. We will see how to do this next. 


Generating Music 


Now that we have written a program to generate one musical note, it will 
be almost trivial to develop a program that actually plays a short tune. All 
we have to do is link single notes together in the orders, and for the durations, 
dictated by the sheet music for the tune. 


Consider the Applesoft SONG program in Table 9-4. This program contains 
several DATA statements that contain the HALFTIME and LENGTH values 
needed by NOTE for each of the notes in the first part of the theme from the 
television series “M*A*S*H.” The LENGTH values have been calculated by 
assuming that a whole note has a duration of one second; if this is the case, 
then LENGTH = 115, as explained earlier. To play the tune defined by the 
DATA statements, first ensure that the NOTE program has been saved to 
diskette and then enter the Applesoft RUN command. SONG plays the tune 
by executing an Applesoft FOR/NEXT loop that reads the HALFTIME and 
LENGTH values for a note, POKEs them into the NOTE program data area, 
and then CALLs the NOTE program to generate the tone. After all the notes 
have been played in this way, the program ends. 


You can easily play your own favorite song by translating its notes into 
HALFTIME and LENGTH values and placing these values into the DATA 
statements of the SONG program. The last pair of values in the DATA state- 
ments must be zeros so that SONG will know when all the notes have been 
read. 


You may well be wondering whether you can play chords of music, that is, 
more than one note at once, in order to improve the quality of the sound that 
is generated. The short answer is ‘“‘yes, you can!”’ but the software required 
to do this is much more complex. For example, to play two notes at once, you 
would have to intertwine two timing loops, one for each note, and you would 
have to ensure that the speaker was being toggled at the proper rate for each 
note. This is not an impossible feat to be sure, but it is left as an exercise for 
the more interested reader. 


LE PUTT WO4s LFZLON OF SBYyoue vg | dON Gl V4 * bles 


Jo} ayesusdwod SqdQN as5ay1! dON Wiis 8h Ya 'ELED 
L17¥iS awe Zt €@ VL Ob ‘OLE@ 
yayeeds ay}, af66oy1: NaxvadS vat 91 @9 @€ GY :aqgEa 
ayou ay} 40 YyyOuaT ayy suTeyuod Xs JWILIJTVH xaq LJLON SL €8 06 3H :¥OED 
dW3L7 Ls bL €@ 42 a8 ‘LOBED 
HILONIST var El €0@ 18 Gv ‘peEa 
auay syye7s wesuboud ayy: SSz# Ad JiON 2 ji OY *20E8 
Ly 
995N SSzg*epE 4$O S]TuN ut uot yen: 62 did HLONIT 61 Gl :10€9 
Cbe*zy/CAouanbaus/s,) = § €€ gid 3WILITWH G LZ *@6E9 
8 
QBE$ OAD l 
9 
UOTLBEIOT O/]I wayeads: 9€09$ NOI ANsnNvIdS S 
b 
HHHEREH HH € 
* JLON * Z 
HHREHHERES L 


‘Iayeods s 3// ay} UO 9j0U [VOISNUL & AvTd 0} UTeIsOId B—ALON *€-6 FIG2L 


260 [___] Inside the Apple //c 


[ _] 261 


9 / The Speaker 


saToA2 pe st awti doo: 


paynoaxs you ST G62-/Z SAUTT UT 
Spod ay} uaym aut} doot ayy 4Nn0 
uaAa a yesusdwoo SYgOQWN aseayL 


er eo& 8H 


sazToAo sszepe Auana sty. aonpay: 
SaToA2 pe St awty door: 


Aouanbauy ayy yyIM 

Auen 1,u0p ,,4yzyGuaT,, 4O Sytun 

247 724} OS |aweS By} aue SauwTy 
dooT [TBuano 3yy 184} aunsua Aayy 


son 8h oh 6H 


EVIWILS 

L1X3 
dW3l) 
2 11¥LS 


Sila 
034 
INd 
X3qd 
dON 
dON 
dON 
dON 
dON 
ING 
03d 
J4d 
JINd 
A3d 
dON 
dON 
dON 
dON 
dON 


dW311 


LIX4 


EVIVLS 


¢ 11¥lS 


bTIWLS 


Orv 
6E 
8E 
LE 
9E 
SE 
bE 
EE 
c€ 
Le 
BE 
Ge 
8¢ 
Le 
9¢ 
S2 
be? 
Ed? 
A 
Le 
O¢ 


EO 


Jd 
| 


S@ 
09 
dd 
£0 


09 
04 
0d 
V9 
V3 
V3 
¥3 
V3 
VI 
6d 
83 
che 
8d 
88 
V4 
VI 
V3 
VI 
v3 


262 [___]| Inside the Apple //c 


Table 9-4. SONG—a program that plays a song on the //c’s speaker. 


@ REM "SONG" 

1886 PRINT CHRS$ €4);"BLOAD NOTE 
06 

11@ READ HT: READ LN: REM READ 

HALFTIME AND LENGTH 

120 IF HT = @ AND LN = @ THEN 1 
60 

13@ POKE 768,HT: POQKE 769,LN 

149 CALL 77@: REM PLAY THE TONE 


159 GOTO 118: REM AND GET NEXT 
NOTE 

168 END 

10908 REM NAME THAT TUNE?! 

1918 DATA 63,29,67,29,63,29,6/7, 
29,63,29,6/7,29,75,58 

10928 DATA 67,29,75,29,6/7,29,/5, 
29,67,29,/5,29,84,29,67,29,7 
5,29,84,29,/5,29,84,29 

19380 DATA 75,29,84,29,89,29,75, 
29,84,29,89,29,84,29,89,29,8 
4,29,75,29,67,58 

1048 DATA 67,58,56,29,58,29,56, 
29,58,29,56,29,58,29,56,58,5 
6,29 

1050 DATA $8@,29,56,29,50,29,56, 
29,50,29,56,58,56,29,6/7,29,5 
6,29,50,29,42,29 

1868 DATA 38,29,42,29,59,29,56, 
eg 

1878 DATA $58,115,50,58,50,29,56 
,29,67,29,56,29,59 ,29,42,29 

1988 DATA 38,29,42,29,58,29,56, 
29,58,115,508,58 

18986 DATA 9,80: REM END OF DATA 

MARKER 
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Further Reading for Chapter 9 


On the speaker ... 


‘Apple Noises and Other Sounds’, Apple Assembly Line, February 1981, pp 
2—9. Generating sound effects using the speaker. 


B.C. Detterich, ‘Apple Free Speech”, Call -A.P.P.L.E., September 1981, pp 
9-14. Using the Apple II speaker to generate voice and sound. 


J.H. Bender, ‘‘Pitch and Rhythm on the Apple”, Call -A.P.P.L.E., June 1982, 
p. 15. More on music for the Apple. 


B. Sander-Cederlof, “Your Apple Can Talk’, Apple Assembly Line, November 
1982, pp. 2-9 
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Mouse and Game 
Controller Input 


In this chapter we will be examining in detail how to use the I/O connector 
located on the back panel of the //c at the far left (as viewed from the back 
end). This port is primarily used to interface two types of related input devices 
to the //c: the Apple mouse and the game controller. These two devices are 
related in that they both provide positional information to the //c. That is, it 
is possible for the //c to determine where a mouse is located on the desktop 
or how far a game controller knob has been rotated. 


Unfortunately, you cannot simultaneously connect a game controller and 
a mouse to the //c because both devices use the same connector. Fortunately, 
however, this limitation is recognized by the //c’s built-in firmware and it is 
possible to read positional information from the mouse as if it was a real 
game controller. This means that you can use the mouse with most software 
that is designed for use with standard game controllers. We'll see how to do 
this later in the chapter. 


The Apple Mouse 


What is a mouse, anyway? Well, it’s simply another input device that can 
be used to transmit useful information to the //c. The information that it 
transmits, however, is not like the ASCII codes that a keyboard delivers, or 
the 8-bit bytes of data that a disk drive delivers, but rather is information 
relating to the position of the mouse on a two-dimensional X-Y plane (that’s 
mathtalk for desktop). Software can easily be written to translate the mouse’s 
position into a coordinate on the video screen so that a cursor or pointer can 
be displayed that keeps in step with the movement of the mouse. 


One of the main advantages of mouse-based software is that you usually 
don't have to use the keyboard in order to select options or enter commands. 
Instead, all you have to do is move the mouse until the screen pointer is 
positioned in the area of the screen that contains the symbolic representation 
of the command you want performed (either a pictorial icon or a command 
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phrase), and then click the mouse button. People who can't type like this 
technique a lot! As all users of the Apple Macintosh computer know, mouse- 
driven software can also be incredibly easy to learn. 


As far as the //c is concerned, the mouse is a port 4 device. This means that 
the firmware that controls it can be accessed by using the Applesoft PR#4 
and IN#4 commands. We'll see examples of this later on in this chapter. 


How the Mouse Works 


The mouse is quite an interesting device. The actual mouse unit itself is a 
small, rectangular, box-like structure with a flat push button on top. The 
status of the mouse button (“pressed” or “‘not pressed’’) can be monitored by 
reading a special I/O location in the //c’s memory. Electrical signals from the 
mouse unit are transmitted to the mouse connector at the back of the //c 
through a long cord (the “‘tail’’). 


Inside the mouse is some special electronic circuitry that is responsible for 
translating the motion of the mouse into a stream of electrical signals that 
the //c can decode and transform into horizontal (X) and vertical (Y) coordi- 
nate information. This information can then be used to position a cursor or a 
pointer on the video screen. 


If you turn the mouse unit over, you will see a small rubber ball poking out 
of a cavity inside. When the mouse is moved across the table, this ball rotates; 
it is this rotational movement that allows the mouse to transfer positional 
information to the //c. 


Inside the cavity that the ball occupies are two small, cylindrical rollers 
that have been arranged at a 90 degree angle to one another so that one will 
turn when the mouse is moved in an up/down (Y) direction and the other will 
turn in response to left/right (X) movement. Of course, if the mouse is moved 
diagonally, then both rollers will be set in motion. 


Passing through the centre of each roller is a long metal axle, one end of 
which is connected to the centre of a small flat disk that has several slits 
symmetrically arranged around its circumference. As the roller turns, so does 
the axle and the disk. The movement of the disk will cause a narrow beam of 
light that is aimed from a tiny infrared light source on one side of the disk to 
a photoreceptor on the other side to alternately pass through unaffected or 
be blocked, depending on whether or not a slit is in the path of the beam. 
Thus, the electrical output from the photoreceptor will either be 1 (light beam 
not blocked) or @ (light beam blocked) and a square wave signal will be 
generated when the mouse is moved. This square wave is passed down the 
mouse’s tail to the //c where it can be used to generate a 65CQ@2 IRQ interrupt 
on each rising edge (or, alternatively, each falling edge) of the square wave. 
The two square waves that are generated (one for each roller) are called X@ 
and YO. 
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When an interrupt is generated by movement of the mouse, you can deter- 
mine the axis of movement (X or Y, or both) by examining two I/O status 
memory locations. Electronic circuitry inside the mouse also provides infor- 
mation on the direction of movement along each axis (up or down, left or 
right) and this information can be read by examining two other I/O memory 
locations. 


The //c has a special built-in interrupt-handling subroutine that responds 
to mouse interrupts and is responsible for monitoring the mouse’s position 
and button status. Whenever a program needs updated mouse information, 
it simply calls a built-in firmware subroutine. We will be looking at how to 
do this later in this chapter. 


Mouse Operating Modes 


The mouse can be operated in one of four fundamental modes: 


@ Passive (or transparent) mode 
@® Movement interrupt mode 
® Button interrupt mode 


@ Movement or button interrupt mode 


A mode is selected by sending a command to the port 4 firmware that is 
built-in to the //c. We will see how to do this in later sections of this chapter. 
(In summary, it involves calling a subroutine called SETMOUSE with a mode 
control byte in the accumulator.) 


If you will be using one of the interrupt modes, then you must make abso- 
lutely sure to install an interrupt-handling subroutine first. As we saw in 
Chapter 2, this can be done by loading the subroutine into memory and then 
placing its starting address in locations $3FE and $3FF (low-order byte first). 
If you don’t do this, you will likely enter limbo when the first interrupt occurs. 


You should note that mouse interrupts are synchronized with the //c’s 
vertical blanking (VBL) interrupt signal that we briefly discussed in Chapter 
7. This means that a mouse interrupt signal will not actually be recognized 
until such time as the video display starts a vertical retrace operation (this 
happens every 1/60 of a second). 


Passive (Transparent) Mode 


In passive mode, the mouse position and button status are constantly being 
updated ‘‘behind the scenes” and no interrupts are passed through to a user- 
installed interrupt-handling subroutine when they change. It is the respon- 
sibility of the program that is running to periodically read the mouse coor- 
dinates and button status to see if they have changed. 
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You should note, however, that even in passive mode, mouse interrupts are 
still occurring since this is the only way in that the //c can properly track 
mouse motion. These interrupts are serviced internally, however, and are not 
passed through to the user. 


Movement Interrupt Mode 


If movement interrupt mode is selected, the //c will pass control to your 
own interrupt-handling subroutine whenever the mouse is moved. This sub- 
routine can identify the source of the interrupt as the mouse button by calling 
the READMOUSE subroutine and then checking to see if bit 1 of MOUSTAT 
($77C) is set to 1. The READMOUSE subroutine and the MOUSTAT status 
location will be discussed in detail later in this chapter. 


Button Interrupt Mode 


At the beginning of this chapter, when we reviewed how the mouse works, 
we mentioned that the mouse generates interrupts whenever it is moved. We 
did not mention, however, anything about a button interrupt signal. There 
was a very good reason for this, of course: the mouse button has not been 
designed to generate interrupts! How then can a button interrupt mode be 
supported? With software mirrors of course! 


When button interrupt mode is selected, the //c automatically enables the 
VBL interrupts and when such an interrupt occurs, the status of the mouse 
button is examined. If the button is being pressed, the //c passes control to 
your own interrupt-handling subroutine that can identify the source of the 
interrupt as the mouse button by calling the READMOUSE subroutine and 
then checking to see if bit 2 of MOUSTAT ($77C) is set to 1. 


Movement or Button Interrupt Mode 


This mode is simply a combination of the movement interrupt mode and 
the button interrupt mode. In this mode, a 65CQ@2 interrupt will be passed 
through whenever the mouse button is pressed or the mouse is moved. 


Vertical Blanking Interrupts 


It is also possible to interrupt the //c every 1/60 second by enabling the 
vertical blanking (VBL) interrupt signal. As we saw in Chapter 7, this interrupt 
is generated immediately after the video display has been refreshed when the 
video electron beam begins retracing to the top left-hand corner of the screen. 
The //c allows you to enable or disable VBL interrupts when any other mouse 
mode is selected or even when the mouse is off. 
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The Mouse and Applesoft 


Perhaps the simplest way to become acquainted with the mouse is to learn 
how it can be controlled from an Applesoft program. This is simple because 
there are really only three commands with which we need be concerned. 
These commands perform the following functions: 


@ Turning the mouse on 
® Turning the mouse off 


® Reading the mouse coordinates and the mouse button 


If you want the mouse to perform fancier tricks, such as interrupting the 
system whenever it is moved or its button is pressed, then you will have to 
rely on assembly language instead. Let’s leave that particular subject for 
later, however. In the meantime, let’s look at the three mouse-control func- 
tions that can be executed directly from Applesoft. These functions are sum- 
marized in Table 10-1. 


Turning the Mouse On 


The mouse can be turned on by executing an Applesoft program line that 
looks something like this: 


1960 PRINT CHR$ €4);"PR#4": PRINT CHRSC1) 


Pretty simple, isn’t it? This Applesoft statement simply redirects output to 
the port 4 firmware that controls the mouse interface (with a PR#4 command) 
and then sends ASCII code 1 (CONTROL-A) to the firmware. This code is 
interpreted by the mouse firmware to mean “turn on the mouse.” Only when 
the mouse is on can its position and button status be read. 


After the mouse has been turned on in this way, it is a good idea to execute 
a line such as this: 


298 PRINT CHR$ €4);"PR#9" 


in order to ensure that any subsequent output gets sent to the video screen 
instead of the mouse firmware. (Change that PR#0 to a PR#3 if you are in 
80-column mode.) 


You can also turn the mouse on by entering commands from the keyboard 
when in Applesoft direct mode (that is, when then “]’’ prompt symbol is being 
displayed). To do this, first enter 


PR#¥4 [Creturn] 


and then press [control-A] followed by the [return] key. After you've done 
this, enter 
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PR¥@ Creturn] 
or 
PR¥3 [Creturn] 


to redirect output to the video screen. 


Turning the Mouse Off 


The procedure to follow to turn the mouse off is as simple as the one used 
to turn it on. To turn it off, execute the following program line: 


180 PRINT CHRS$ €4);"PR#4"%: PRINT CHRSCO) 


The mouse firmware interprets ASCII code @ (the null) as the mouse off 
command. The above line should always be followed by one that redirects 
output to the video display: 


C08 PRINT CHR$ €4);"PR#6"%: REM 40- 
COLUMN DISPLAY ON 


or 


C88 PRINT CHR$ C4);"PR#3":REM 88- 
COLUMN DISPLAY ON 


The series of keyboard commands that can be entered to turn off the mouse 
are as follows: 


PR¥4 [Creturn] 
Ccontrol-@]}] [Lreturn] 
PR¥Q [return] or PR#3 [return] 


Reading the Mouse 


Now we know how to turn the mouse on and off. This information isn't 
much good to us, however, unless we also know how to read the data that 
defines the mouse’s position and the status of its button. Read on to find out 
how to do this. 


Before valid mouse data can be read, the mouse must be turned on as 
described above. When the mouse is on, its data can be read by selecting the 
mouse firmware in port 4 for input by executing a program line like this: 


10@ PRINT CHR$ €4);"IN#4" 


Once this has been done, the current X and Y coordinates of the mouse, and 
the status of its button, can be read by executing the following statement: 


208 %&I INPUT "";X,Y,B 


where X, Y, and B represent any three Applesoft numeric variables. You 
should note two important features of this INPUT statement: 
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@ The null string in the INPUT statement has been included to prevent the 
display of the question mark prompt that an INPUT statement usually 
uses. 


@ The three variables are all part of the same INPUT statement. The 
variables cannot be read in with separate INPUT statements. 


After the INPUT statement has been executed, the mouse’s horizontal (X) 
position will be in variable X, the vertical (Y) position in variable Y, and the 
mouse button status code in variable B. 


The X and Y coordinates of the mouse will be in the range @ .. . 1023. The 
absolute value of the button status code represents the current status of the 
mouse button and its status the last time the mouse was read. These status 
codes are summarized in Table 10-2. 


Table 10-2. Button status codes for the mouse. 


Status 

Code* Description 
| Button is being pressed and was pressed last time. 
2 Button is being pressed and was released last time. 
3 Button is released and was pressed last time. 
4 Button is released and was released last time. 


* Absolute value. If the status code is negative, then a key has been pressed. 


For example, if the button status code is 3 (or —3), then the mouse button 
is not being pressed, but it was being pressed the last time that you requested 
mouse data. 


If any key that generates an ASCII code has been pressed on the //c’s key- 
board, then the button code will be negative. In this situation, you should 
always read the keyboard (with a PEEK(49152) command) to get the keystroke 
and then clear the keyboard strobe (with a POKE 49168,0 command). If you 
don’t clear the keyboard strobe, then the button code will remain negative 
even though no new key has been entered. 


A Sample Program 


All of the techniques we have described above have been used in the pro- 
gram called MOUSE.DEMO in Table 10-3. The body of this program is a 
simple loop that continually reads the mouse and displays its current X and 
Y coordinates and button status code on the screen. 


Move the mouse around on your desktop while this program is running and 
notice how the X and Y coordinates change. As expected, they always range 
between @ and 1023. 
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Table 10-3. MOUSE.DEMO—a program to demonstrate how to read 
the mouse from an Applesoft program. 


8 REM “MOUSE.DEMO" 

1980 D$ = CHR$ ¢€4) 

11@ KB = 49152: REM KEYBOARD I/O 
LOCATION 


120 KS = 49168: REM KEYBOARD ST 
ROBE I/0 LOCATION 

130 TEXT : PRINT CHR$ €21): HOME 

POKE 34,3 
140 PRINT "APPLE //c MOUSE DEMO 
[Press ESC to end]J" 

15@ PRINT "X VALUE Y VALU 
E BUTTON" 

168 PRINT D$;"PR#4": PRINT CHR$ 
C1): PRINT D$;"PR#O": REM TU 
RN ON MOUSE 

1786 PRINT D$;""IN#4": REM READ M 
OUSE 

18@ INPUT """:X,Y,B 

198 IF B « @ THEN KY = PEEK CK 
Bd: POKE KS,@: IF KY = 155 THEN 
230 

21@ VTAB S: PRINT X,Y,B 

cob 6GOTO 189 

230 PRINT D$;"IN#O": REM DON’T 
READ MOUSE 

2406 TEXT : HOME END 


You will also notice that the button status code is 4 if you haven't touched 
the mouse button; referring to Table 10-2, this means “the button is released 
and it was released the last time, too.’ If you quickly press the mouse button 
and then release it (that is, you “click”’ it), however, the button status will 
first change to 2, and then 3, before returning to 4 again. If you press the 
mouse button, keep it down for a while, and then release it (that is, you 
‘press’ it), the button status will first change to 2, then to | until you release 
the button, then to 3, and finally back to 4. You can see that these codes make 
sense by referring to their descriptions in Table 10-2. 


The Mouse and Assembly Language 


Controlling the mouse from an assembly-language program would be a 
rather complex chore if it was necessary to write the fundamental I/O drivers 
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needed to communicate with it. Fortunately, the //c’s firmware contains a set 
of eight useful subroutines that can be used to control the mouse without the 
necessity of dealing directly with machine-specific I/O locations. The starting 
addresses for these subroutines are stored in the form of offsets from the start 
of page $C4 of memory in a table beginning at location $C412 in the //c’s ROM 
area. Thus, if an entry in this table is $3D, the starting address for the 
subroutine defined by that entry is $C43D. The names for these subroutines, 
and their positions in the table of offsets is shown in Table 19-4. 


Table 10-4. Offset locations for mouse subroutines. 


Subroutine Name Location Where Offset Stored 
SETMOUSE $C412 
SERVEMOUSE $C413 
READMOUSE $C414 
CLEARMOUSE $C415 
POSMOUSE $C416 
CLAMPMOUSE $C417 
HOMEMOUSE $C418 
INITMOUSE $C419 


The easiest way to call a mouse subroutine is to store its starting address 
in two consecutive memory locations (low-order byte first, of course) and then 
use an indirect JMP instruction to pass control to it. For example, if you 
determine the starting address to be $C43D, then you can call the subroutine 
by storing $3D in location $300, $C4 in location $301, and then executing a 
“IMP ($0300) instruction. 


You should make it a practice to always communicate with the mouse by 
using the built-in mouse subroutines in this way. If you do, then your software 
will be compatible with the version of the mouse used with earlier members 
of the Apple II family. 


Mouse Screen Hole Locations 


The mouse firmware makes use of several main memory screen holes for 
data storage. As you will recall from Chapter 7, screen holes are memory 
locations that, although they are located within the //c’s primary text page 
from $400 ...$7FF, are not used for video display purposes and are not 
affected by the //c’s built-in video output subroutines.. The main memory 
screen holes used by the mouse firmware are summarized in Table 10-5. The 


corresponding locations in auxiliary memory are also used by the mouse for 
the storage of default parameters. 
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There are three important points to keep in mind before a mouse subroutine 
is called: 


® 65C02 interrupts must be disabled before calling the subroutine and 
re-enabled after the subroutine ends. A program that does this will 
look something like this: 


PHP -Save status 
SE | ;Disable interrupts 


Ccall mouse subroutine] 


PLP Restore status 
Cincluding interrupts) 


@ The mouse X coordinate, MOUXL ($47C) and MOUXH ($57C), Y coor- 
dinate, MOUYL ($4FC) and MOUYH ($5FC), and status byte, MOUSTAT 
($77C), must be moved to data areas within your program before re- 
enabling interrupts after calling a mouse subroutine. If you don’t do this 
and you try to read mouse data directly from the screen holes after calling 
a mouse subroutine, the data you read will be wrong if another mouse 
interrupt occurs before you have done so. 


@ The 65CQ@2 X and Y registers must be set equal to $C4 and $40, respectively 
(‘4” is the mouse port number). 


Comparing the //c Mouse with the //e Mouse 


Before we take a close look at each of the mouse subroutines, let’s outline 
the important differences between the //c mouse and the mouse that is used 
with earlier members of the Apple II family (for convenience, we'll call it the 
“/fe mouse’). 


The //e mouse is interfaced to the Apple //e through an interface card that 
is inserted into one of its seven peripheral expansion slots. This card contains 
a special microprocessor that is solely responsible for monitoring the status 
of the mouse and for sending an active interrupt signal to the IRQ line on the 
/le’s 6502 microprocessor only when a mouse interrupt mode has been selected. 
When current mouse data is needed, it must be transferred from this interface 
card into the //e’s screen hole locations. 


The //c, on the other hand, contains no alternative microprocessor dedicated 
to the control of the mouse. Mouse control is the responsibility of the same 
65C02 that executes all your programs. In order to keep tabs on what the 
mouse is up to, the //c fixes things up so that a 65C@2 IRQ interrupt signal is 
always generated whenever the mouse is moved. The //c’s built-in interrupt- 
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handling subroutine traps this interrupt before it can get to the user-installed 
interrupt-handling subroutine, updates the mouse’s X and Y coordinates in 
the main memory screen holes, and changes MOUSTAT ($77C) to reflect the 
new status of the mouse. This interrupt is only passed on to the user-installed 
interrupt-handling subroutine if a mouse movement interrupt mode is active. 
Mouse button interrupts are generated by enabling VBL interrupts when this 
mode is selected, polling the button I/O location, RD63 ($C0@63), whenever a 


VBL interrupt occurs, and passing the interrupt through if the button is being 
pressed. 


The key differences between the //e mouse and the //c mouse are as follows: 


@ The //e mouse never tries to interrupt the 6502 unless a mouse interrupt 
mode is active; the //c mouse always tries to interrupt the 65C02 when 
the mouse is moved (assuming that the mouse is on, of course). 


@ The current data for the //e mouse is stored on the mouse interface card 
until it is specifically transferred to the main memory screen holes; the 


current data for the //c mouse is always found in the main memory screen 
holes. 


®@ The //c mouse will not appear to function in passive mode if 65CQ@2 
interrupts have been disabled with a SEI instruction because its move- 
ment interrupts will be ignored; the state of the interrupt flag has no 
effect on the operation of the //e mouse in passive mode. 


In the descriptions of the mouse subroutines that follow, you will see ref- 
erences to ‘mouse position registers.’ These are the mouse data registers that 
are located on the //e mouse interface card only; they do not exist on the //c. 
It is important, however, to pretend that they do exist on the //c so that any 
software that you do develop will work properly with the //e mouse. For 
example, the READMOUSE subroutine is used to transfer data from the 
mouse position registers to the screen hole locations corresponding to the X 
and Y coordinates and the mouse status location. We know that this really 
isn t necessary on the //c because those registers don’t exist and the current 
mouse data is already in the right place, ready to be read, but if you choose 
not tocall READMOUSE whenever you want to get mouse data, your program 
won't run properly with the //e mouse. 


The Mouse Subroutines 


Let’s take a close look at each of the subroutines right now. 


SETMOUSE. This subroutine is used to set up the mouse mode. This is 
done by placing the mouse mode code in the accumulator and then calling 
this subroutine. The valid modes are as indicated in Table 10-6. On exit, the 


65C@2 carry flag will be clear if the mode was valid; it will be set if it was 
invalid. 
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Table 10-6. Valid mouse mode bytes. 


Mouse Mode Byte Description 
$00 Mouse off 
$01 Passive (transparent) mode 
$03 Movement interrupt mode 
$05 Button interrupt mode 
$07 Movement or button interrupt mode 


Note: Add 8 to the mode byte value if vertical blanking interrupts are to be active. 


SERVEMOUSE. This subroutine should be called as part of an interrupt- 
handling subroutine to determine whether the mouse or vertical blanking 
signal was the source of the interrupt. If either one was responsible, then the 
65C@2 carry flag will be clear (@); otherwise, it will be set (1). This subroutine 
also sets up the mouse status location, MOUSTAT ($77C), so that it can be 
examined to determine the exact type of mouse interrupt that occurred. A 
complete description of MOUSTAT can be found in Table 10-5. 


READMOUSE. This subroutine must be called to read the mouse position 
registers and place them in the memory locations used to store the mouse’s 
X and Y coordinates. These memory locations are as follows: 


X coordinate : $47C (low), $57C (high) 
Y coordinate : $4FC (low), $5FC (high) 


This subroutine also clears bits 1,2,and 3 of MOUSTAT ($77C), the interrupt 
bits, and adjust bits 5, 6, and 7, the movement and button status bits, as 
necessary. 


CLEARMOUSE. This subroutine sets the mouse’s X and Y coordinates 
and position registers to @. The button and interrupt bits in MOUSTAT ($77C) 
are not changed. 


POSMOUSE. This subroutine sets the mouse position registers to the 
same values stored in its X and Y coordinates. 


CLAMPMOUSE. This subroutine is used to set the clamping boundaries 
for the X and Y coordinates. Any mouse position below the clamping mini- 
mum will automatically be set to that minimum. Similarly, any position 
above the clamping maximum will be set to that maximum. Before calling 
this subroutine, the new clamping limits must be set up as follows: 


$478 (low), $4F8 (high) for clamping minimum 
$578 (low), $5F8 (high) for clamping maximum 


and the accumulator must be set equal to @ if the clamping limits for the X 
coordinate are being set, or to 1 if the clamping limits for Y are being set. 
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HOMEMOUSE. This subroutine changes the mouse position registers to 
the coordinates of the upper left corner of the clamping window. 


INITMOUSE. This subroutine is normally the one that is called before the 
mouse is used. It sets up the initial default values for the mouse: a clamping 


window from $@ to $3FF for the X and Y coordinates and an initial position 
of (0,0). 


A Sample Program 


The MOUSE.IRQ program in Table 10-7 shows how the mouse subroutines 
and mouse interrupts can be handled by an assembly-language program. 
When this program is executed, it first stores the address of a mouse interrupt- 
handling subroutine at $3FE/$3FF, the IRQ user-vector locations. The mouse 
is then initialized by calling INITMOUSE. 


The mouse button/movement interrupt mode is then set by calling SET- 
MOUSE with the appopriate mouse mode code ($07) in the accumulator. 
Finally, the mouse coordinates are zeroed by calling CLEARMOUSE and 
65C0@2 interrupts are enabled by executing a CLI instruction. 


After this has been done, when the mouse is moved or its button is pressed, 
the //c’s firmware will pass the interrupt that is generated on through to the 
IROHNDL interrupt handler. This subroutine does what all good mouse 
interrupt handlers should: it calls SERVEMOUSE to see if the mouse caused 
the interrupt. If the mouse is not responsible, the carry flag is set. If it is a 
mouse interrupt, then MOUSTAT is examined to see what caused it (a move- 
ment or a button press). If it is a movement interrupt (bit 1 of MOUSTAT is 
1), then a “M” is displayed on the video screen; if it is a button interrupt (bit 
2 of MOUSTAT is 1), then a “B” is displayed. 


You should take particular note of the MOUSER subroutine that is called 
to execute all mouse subroutines that MOUSE.IRQ uses. On entry to MOUSER, 
the X register must contain the number of the mouse subroutine that is to be 
called; this number is simply the relative position of the subroutine’s offset 
within the table starting at $C412 (0 for SETMOUSE, 1 for SERVEMOUSE, 
and so on). MOUSER gets the proper offset and stores it at MOUSE so that 
the subroutine can be jumped to with a ‘‘JMP (MOUSE)” instruction. It then 
disables interrupts and calls the mouse subroutine before ending. 


The Mouse as a Joystick 


Many games available for the //c require the use of a game controller or a 
joystick. (A joystick is essentially the same as two game controllers, one that 
controls the X direction and the other that controls the Y direction.) Since 
these devices can only be connected to the same interface that the mouse uses, 
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you would think that you would have to disconnect the mouse and connect 
the game paddles or joystick before you could use these games. 


Fortunately, the //c can be configured in such a way as to “‘trick”’ it into 
thinking that the mouse is a joystick. Once the //c has been so configured, the 
standard Applesoft paddle reading commands, PDL(@) and PDL(1), or the 
system monitor paddle reading subroutine, PREAD ($FB1E), will take their 
values from the position of the mouse and will not attempt to read the position 
of the non-existent joystick. 


If you want the //c to interpret the mouse as a joystick, then all you need do 
is turn on the mouse in passive mode. You will recall that this can be done 
by entering the following series of commands from the keyboard: 


PR#4 [return] [control-A] Creturn] PR#9 Creturn]) 


After this has been done, your game disk can be booted and it should work 
fine with the mouse. Note, however, that if the software that you are using 
does not use the Applesoft PDL(®) and PDL(1) commands or the system mon- 
itor PREAD subroutine, then this technique will not work. 


Mouse I/O Locations 


The //c supports several soft switch and status locations that can are used 
to monitor the status of the mouse and the vertical blanking signal. These are 
summarized in Table 10-8. 


Since the mouse primarily communicates with the //c by generating inter- 
rupt signals, it is not surprising that most of the mouse I/O locations have 
something to do with interrupts. Most of them perform one of the following 
functions: 

@ Select when an interrupt is to be generated 
Enable and disable interrupts 
Read the interrupt status 


Clear interrupt conditions 


Read the status of the interrupt enable/disable soft switches 


For example, RX®EDGE ($C@5C) and FX@EDGE ($C@5D) can be used to 
select whether a mouse interrupt is to occur on the rising or falling edge, 
respectively, of the mouse’s X@ signal. The corresponding locations for the YO 
signal are RYOEDGE ($C@5E) and FYOEDGE ($CO5F). 


Mouse XO and YQ interrupts can be enabled by accessing ENBXY ($CQ@59) 
or disabled by accessing DISXY ($C058). Similarly, vertical blanking inter- 
rupts can be enabled by accessing ENVBL ($C@5B) or disabled by accessing 
DISVBL ($CO5A). 


Note that the eight soft switches we have just referred to (from 
$CO58 ... $CO5F) can only be used if IOUDISOFF ($C07F) is first written to. 
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When an interrupt occurs, it is nice to know what caused it. This can be 
deduced by examining one of several status I/O locations. If the interrupt was 
caused by the up/down movement of the mouse, bit 7 of MOUSEYINT ($C017) 
will be 1 (that is, if you PEEK this location, the result will be greater than 
127). The corresponding location to check for left/right movement is MOUS- 
EXINT ($C@15). Vertical blanking interrupts can be detected by examining 
bit 7 of VBLINT ($CQ19). 


After an interrupt signal is generated, it must be cleared by reading another 
I/O location. If this is not done, then other interrupt signals will be generated 
even though no new interrupt has actually occurred. A mouse movement 
interrupt condition can be cleared by reading RSTXY ($CQ48). A vertical 
blanking interrupt can be cleared by reading PTRIG ($C070). 


You can always determine exactly how the interrupt disable/enable switches 
have been configured by examining bit 7 of another set of status locations. To 
check whether mouse movement interrupts are enabled, look at RDXYMSK 
($C040); if bit 7 is 1, then they are. Similarly bit 7 of RDVBLMSK ($CQ41) 
indicates whether vertical blanking interrupts are enabled. RDXOEDGE ($C042) 
and RDYOEDGE ($C@43) can be read to determine whether interrupts are to 
be generated on the falling or rising edge of X@ and YO, respectively. 


The direction of mouse movement along an axis can be determined by 
reading bit 7 of locations MOUX1 ($C0@66) and MOUY1 ($C067). If a mouse 
X@ interrupt has occurred, bit 7 of MOUX1 will be 1 if the mouse has been 
moved to the right or @ if it has been moved to the left. MOUY1 can be 
examined after a YO interrupt to determine whether the motion was up or 
down. 


The status of the mouse button can be determined by reading RD63 ($CQ63). 
If bit 7 is 1 then the button is not pressed; otherwise it is. 


As you can probably appreciate, writing a program to control the mouse is 
a fairly complex chore when you are dealing with the mouse at the lowest 
level by directly monitoring I/O locations. Fortunately, however, you should 
never need to use any of these I/O locations. Instead, you can use the //c’s 
built-in firmware subroutines and interrupt handler to simplify dialog with 
the mouse. 


The Game Controller Interface 


The game controller interface is a very versatile one. As its name suggests, 
it is primarily used to interface devices that allow you to play video games: 
devices such as paddles, joysticks, and push buttons. When interfaced to the 
appropriate supporting circuitry, however, it can also be used to detect light 
levels, measure the temperature, and perform many other interesting and 
useful feats. 
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O 
PDLO N.C. GND 


DB-9 connector 
(looking in) 


N.C. POL1 PBO NC. 


NOTES: PB =push button (switch) input 
POL =game controller (paddle) input 


GND = electrical ground 
+5v =+5 volts 
N.C. = not used 


Figure 10-1. Pinout diagram for the game connector. 


A pinout diagram for the game connector is shown in Figure 10-1. We will 
be referring to this diagram throughout the remainder of this chapter as we 
propose several simple interfacing projects that use the signals available 
through the game connector. 


Of the 9 pins on the main game connector, three are not used, two are used 
for the power supply connections (+5 volts and electrical ground) and four 
are used for one-bit inputs (2 switch inputs and 2 analog inputs). All of these 
signals will be discussed in detail in the following sections. 


Game Controller Inputs 


There are two game controller input pins (also called “paddle” inputs) on 
the game connector (PDL@ and PDL1), that are normally used to interface 
two game paddles or one joystick to the //c. These inputs are also often referred 
to as the analog inputs. Each PDL input is associated with a unique I/O 
memory location, as shown in Table 10-9. Only bit 7 of these locations is 
meaningful as we will see shortly. 


The game controller inputs are designed to be used with analog devices 
capable of changing their internal resistances in the range 0-150K ohms in 
response to a physical phenomenon that is to be measured (such as the 
position of a game paddle or joystick, the temperature, or air pressure). Such 
devices are called ‘transducers’ because they are converting a physical phe- 
nomenon into an electrical quantity (resistance) that can be quantified by a 
digital computer like the //c. 


Each PDL input is part of an analog-to-digital (A/D) conversion circuit that 
allows an analog resistance value to be converted (by software) into a digital 
quantity the //c can handle. The resistor forms part of a simple “RC” (resistor- 
capacitor) timing circuit that sets the time constant of a special integrated 
circuit called a NE556 Timer. When this timer is reset, by accessing PTRIG 
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Table 10-9. Game controller I/O memory locations. 


Address 
Hex (Dec) Usage Symbolic Name _ Action Taken (or Status) 
$CQ064 (49252) R7 PDLO 1 = game controller 0 has 
not timed out 
$C065 (49253) R7 PDLI1 1 = game controller 1 has 
not timed out 
$CO70 (49264) R PTRIG Reset the game controllers 


Note: “R7” means “read and check bit 7 to determine the status.” 
“R7” means ‘‘read from the location.” 


($CO070), bit 7 of each PDL I/O memory location becomes high (1) but will 
eventually become low (@) when the timer “times out,” that is, the period of 
time equal to the time constant for both “RC” circuits has elapsed. 


To interface a variable-resistor device, all you need to do is connect one of 
its leads to + 5v (pin 2) and the other to one of the PDL input pins. A simplified 
diagram for one such circuit is presented in Figure 10-2. Since the maximum 
“R” value recommended by Apple is 150,000 ohms and the “C”’ value is 0.022 
microfarad, the maximum time constant for this circuit is 0.022 x 150,000 
ohms = 0.0033 second. That is, when the resistance is at its maximum, the 
time required for the NE556 Timer to bring bit 7 of the PDL I/O memory 
location low (0) is about 3.3 milliseconds. The time required to do this will 
change whenever the resistance of the device changes because the RC time 
constant will also change. 


By setting up a program that periodically checks to see whether the NE556 
Timer has timed out (by examining bit 7 of the PDL I/O memory location) 
and increments a counter if it has not, you can easily convert the resistance 
to a numerical value that varies linearly with resistance. In fact, Applesoft’s 
built-in paddle-reading functions, PDL(@) and PDL(1), do this for you auto- 
matically—the counter value they return is an integer between @ and 255. 
(You can examine the assembly-language subroutine that these functions use 
by looking at the PREAD ($FB1E) subroutine located in the system monitor; 
it checks for a timeout condition every 11 microseconds.) You should note, 
however, that the PDL functions assume that your input resistance is in the 
range @—-150K ohms. This roughly translates to a time constant that ranges 
from @ to 2.8 milliseconds and to PDL readings between @ and 255.(Remember 
that the PDL subroutine’s counter increments every 11 microseconds until 
the timer has timed out. This means that the maximum allowable time 
constant is 255*11 microseconds, or 2.8 milliseconds.) If the upper limit of 
the resistance is higher than 150K ohms, then there will be a ‘‘dead area’”’ 
where the resistance may change but the value calculated stays at 255; if it 
is lower, then the highest PDL value that can be generated will be less than 
255. 
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The PTRIG ($C070) signal initiates the A/D conversion procedure for both 
game controller circuits at the same time. Since the NE556 Timer will time 
out at different times for each game controller (unless their resistances are 
identical), it is possible that after reading one PDL value that the other game 
controller is still timing out. If an attempt is made to read this other controller 
immediately after reading the first one, only the time needed to complete the 
timing-out process from the first PTRIG will be measured. This leads to a 
spurious game controller signal that is lower than expected. To avoid this 
“crosstalk”’ between paddles, you should wait about 3 milliseconds before 
reading the other game controller; this delay gives the other game controller 
a chance to time out. This can be done in Applesoft by placing a short FOR/ 
NEXT loop between the two PDL functions. Here is an example of how to do 
this: 

10@ X=PDLC@):FOR IT=1 TO 10:NEXT: Y=PDL(1) 


Two devices that are commonly interfaced to the game controller inputs 
are the game paddle and the joystick. A game paddle is a device that controls 
the signal at one PDL input only; it typically takes the form of a knob that 
you can rotate with your hand. As the knob is rotated, the resistance value 
changes linearly. A joystick allows you to control both PDL inputs at once in 
such a way that the two-dimensional position of the joystick can be easily 
detected by reading the two game controller values. 


There is no reason to restrict the game controller inputs to use with game 
paddles and joysticks, however. Any device that provides a fluctuating resis- 
tance value within the 0Q—150K range could also be interfaced and its resis- 
tance converted to a value between @ and 255 using the Applesoft PDLQ) 
commands or their assembly-language equivalents. 


Examples of two such useful devices are a thermistor and a photoresistor. 
A thermistor is a device that changes resistance with temperature. Several 
types of thermistors are available, including types that will generate resis- 
tances within the Q—15@K ohm range for most temperatures that you would 
want to measure. Unfortunately, most thermistors are not sensitive to small 
temperature changes, such as those that might occur in a home, so the range 
of PDL values read may not be large. In addition, the values generated may 
not vary linearly with temperature. Nevertheless, you can calibrate the ther- 
mistor by preparing a table of actual temperatures (measured with a standard 
thermometer) and their associated paddle readings. This will at least allow 
you to estimate the temperature from a given “paddle” reading. 


A photoresistor is a device that changes resistance with the amount of light 
shining on it. The greater the light intensity, the lower the resistance. You 
would calibrate this device by preparing a table of light intensities (as mea- 
sured by a light meter) and their associated ‘‘paddle” readings. 


Let’s hook up a photoresistor to the game connector to show you how it 
works. A handy photoresistor to use is a cadmium sulfide one that is readily 
available from Radio Shack (part number 276-116). All you have to do to 
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interface it to a game controller input, say PDLQ, is to connect one leg of the 
photoresistor to +5 volts (pin 2) and the other leg to PDLO (pin 5). Once you 
have done this, you can read its current setting by using the Applesoft PDL(@) 
command. Enter the following program and then run it: 


198 PRINT PDL C€@) 
208 GOTO 1989 


While the program is running, turn off the room lights to verify that the 
‘paddle’ value increases when there is less light. If you have a dimmer light 
switch, slowly turn the light intensity up and see how the value slowly decreases 
until it goes to @ in very bright light. 


Push Button Inputs 


There are two one-bit input ports on the game connector that are normally 
used to read the state of external switches connected to them. These are the 
so-called “push-button” input ports. These ports, and the switches them- 
selves, are usually referred to by their descriptive names: PB@ and PB1 (or 
sometimes SW@ and SW1). 


The //c assigns one I/O memory location to each of the push-button input 
ports, but only bit 7 at that location is actually used. These locations are 
shown in Table 10-10. By reading the memory location for a particular push- 
button input (using an Applesoft PEEK or an assembler LDA) and examining 
bit 7, you can determine whether a switch is being pressed or not. By conven- 
tion, if the bit is set to 1, then the switch is considered to be on (that is, 
pressed); if it is cleared to @, the switch is considered to be off (that is, released). 
You should note, however, that it is possible for a switch to be connected in 
such a way that exactly the opposite result is observed. More on this later. 


A switch is a simple electrical component. It is typically used to allow you 
to complete an electrical circuit between its two contacts in order to turn 
something on and to break this circuit in order to turn something off. (Some 


Table 10-10. Push button I/O memory locations. 


Address 
Hex (Dec) Usage Symbolic Name _ Action Taken (or Status) 
$CO61 (49249) R7 PBO 1 = push button @ or 
OPEN-APPLE is pressed 
$C062 (49250) R7 PB1 1 = push button 1 or 
| SOLID-APPLE is 
pressed 


Note: ‘‘R7’’ means ‘‘read and check bit 7 to determine the status.” 
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switches can have more than two contacts, but we'll ignore them for the 
moment.) There are many varieties of switches, but the variety that is com- 
monly connected to the push button inputs is, you guessed it, the push button. 
This is because they are ideally suited as triggers for such video game weap- 
onry as laser cannons, machine guns, and so on. 


Switches can be classified into one of two categories: ‘‘momentary contact’ 
or “fixed contact.” A momentary-contact switch is one that returns to its 
initial “resting” position immediately after you take your finger off it. All of 
the keys on the //c’s keyboard (except the CAPS LOCK key) are examples of 
such a switch. 


A fixed-contact switch is one that can be turned on or off and that will stay 
on or off, as the case may be, after you have taken your finger off it. Examples 
of fixed-contact switches are the CAPS LOCK key on the //c’s keyboard, a 
standard light switch, and a toggle switch. 


Two other special terms are used to describe the operation of momentary- 
contact switches: “normally open” and ‘“‘normally closed.” A switch is said 
to be normally open if, when it is not being pressed, no connection is made 
between its contacts. Conversely, a normally closed switch is one in which 
the contacts are closed when it is not pressed. 


It is important to know whether the momentary-contact switch that you 
wish to interface to the game connector is normally open or normally closed, 
because the interface circuit that you must build will be different for each 
type of switch. Figure 10-3 sets out the two alternative circuits. These circuits 
have been designed in such a way that if the switch is not being pressed, then 
the input to the push button pin is grounded and when it is being pressed, it 
is connected to 5 volts. This ensures compatibility with Apple’s on/off push- 
button convention referred to earlier. 


It is easy to install your favorite type of switch, be it momentary contact or 
fixed contact, normally open or normally closed, to the game connector. You 
must install it, however, when the power to the //c is off! Let’s assume you 
have a normally open push button switch and you want to install it as PB1. 
Following Figure 10-3 (a), connect a wire from one switch contact to the + 5v 
line (pin 2 on the game connector), another wire from the other contact to 
PB! (pin 1), and then connect a 1,000-ohm resistor between PB1 (pin 1) and 
ground (pin 3). (This resistor ensures that the input to the connector will not 
““float’’ between 1 and @ when the switch is not pressed and will also prevent 
a short-circuit when the switch is pressed.) 


You can easily determine whether or not a push button is being pressed by 
examining bit 7 of the I/O memory location that the //c reserves for that 
button. As explained earlier, if this bit is on (1), then the button is being 
pressed; if it is off (0), the button is not being pressed. This means that if you 
PEEK this memory location from Applesoft, then the number you read is 


greater than or equal to 128 if the button is pressed or less than 128 if it is 
not. 
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(a) normally-open push button 
PUSH BUTTON 


PB s———» +5 v (pin 2) 


Input 
pin 7 (#0) , 
pin 1 (#1) 1000 ohms 


— GROUND (pin 3) 


(b) normally-closed push button 
PUSH BUTTON 


| in |} GROUND (pin 3) 
npu 
pin 7 (#0) 


pin 1 (#1) ? 1000 ohms 


+5 v (pin 2) 
Figure 10-3. Interfacing push buttons to the game 


Two keys on the //c’s keyboard are actually directly connected to the game 
connector’s push-button input lines. These are the OPEN-APPLE and SOLID- 
APPLE keys that flank the space bar. These two keys are connected to PBQ 
and PB1, respectively. 


The presence of these two keys enables you to easily experiment with the 
concept of game-paddle switches without having to do any circuit design at 
all. Let’s write a simple little program to test the status of PBO, the OPEN- 
APPLE key. 

The I/O memory location reserved for PB@ is 49249. To read this location 


from an Applesoft program, you would use the PEEK(49249) command. Enter 
the following simple Applesoft program and run it: 


108 IF PEEKC49249)>127 THEN PRINT “DOWN WE GO!" 
208 IF PEEKC49249)<128 THEN PRINT " 

BACK UP AGAIN!" 
308 GOTO 1989 


While the program is running, periodically press and release the OPEN- 
APPLE key. You will find that when it is pressed, the message 


DOWN WE GO! 


will appear, and that when it is released, you will see the message 
BACK UP AGAIN! 


By changing the address that is PEEKed, you can easily test the status of 
any of the other push buttons, including the one you wired up yourself. 
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Remember that the switches connected to the push-button inputs on the 
game connector need not be push buttons. Any type of switch can be con- 
nected, including toggle switches, reed switches, blow switches, pressure 
switches, and magnetic switches. 


Further Reading for Chapter 10 


Note: All of the game connector experiments referred to in the following 
articles use the 16-pin game connector that is found on the motherboard of 
the Apple //e, the Apple II Plus, and the Apple II. This connector does not exist 
on the //c. However, the connector signals used in the experiments are avail- 
able on the //c’s mouse/game connector. 


On paddle input in general ... 


P. Baum, “Nibbling at the Game Paddle Port’, Nibble, October 1984, pp. 
100—105. A comparison of the game paddle circuitry in the Apple //c and 
earlier models. 


On reading the game paddles ... 


B. Sander-Cederlof, ‘Reading Two Paddles At the Same Time”, Apple Assembly 
Line, March 1982, p.1.A program to simultaneously read two game paddle 
inputs. 


On interfacing a lie detector ... 


D.B. Curtis, ‘To Tell the Truth’, Kilobaud Microcomputing, August 1981, 
pp. 87-89. How to hook up a lie-detecting device to the game paddle 
inputs. 


On interfacing a joystick ... 


“Dual Joysticks for Under $15.00”, Nibble, Vol. 1, No. 2 (1980), p. 13. How 
to hook up a joystick to the game paddle inputs. 


On interfacing a thermistor ... 


C.J. Kershner, ‘A Digital Thermometer for the Apple II’, Micro, March 
1980, p.21. How to hook up a thermistor to the game paddle inputs. 


On interfacing a light pen ... 


DJ. Lilja, “Build a Simple Light Pen for the Apple II’, Byte, June 1983, pp. 
395—406. How to hook up a light pen to the push button inputs. 


On interfacing a weather map receiver ... 


K.H. Sueker, ‘Apple FAX: Weather Maps on a Video Screen”, Byte, June 
1984, pp. 146-151. This fascinating article describes how you can receive 
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broadcasted weather maps by connecting some circuitry to a push button 
input. 


On TTL logic and digital electronics in general ... 
D. Lancaster, TTL Cookbook, Howard W. Sams and Co., Inc., 1976. 
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The Serial Interface Ports 


Not counting the disk drive, the two most common peripherals attached to 
a microcomputer seem to be a printer and a modem. The reasons for the 
popularity of printers are obvious, so we won't touch on them here. 


Modems are used to communicate with other computers over standard 
telephone lines. These computers can be large mainframes that contain enor- 
mous databases or simply other personal computers like the //c. Modems are 
becoming increasingly popular as more people begin to appreciate the con- 
venience of being able to interactively tap the information stored on a remote 
computer, information that would be difficult to locate in any other way. 


The //c has two built-in interfaces, called serial ports, that allow devices 
such as printers and modems to be easily connected to it. You can take a look 
at these ports by turning the //c around so that its back panel is facing you. 
Serial port 1 is the special 5-pin connector (called a DIN-5 connector) near 
the far right with the small drawing of a printer just above it Serial port 2 is 
on the left side, next to the mouse/game connector, and it has a drawing of a 
telephone handset above it. 


In this chapter we will be examining in detail how to make use of these 
serial ports. Included will be discussions of serial interfaces in general, the 
two ‘'6551” integrated circuits that simplify the data transmission process, 
and the built-in firmware that can be used to control how data is sent to and 
read from serial devices such as printers and modems. 


Serial Transmission of Data 


There are two main methods that are used to transfer data from a computer 
to an external device: the parallel method and the serial method. 


When the parallel method is used, each bit of a byte is simultaneously 
transmitted to the device along eight wires (one for each bit). This method 
typically uses a few extra control (or “handshaking’’) lines: a ‘‘busy”’ line that 
the receiver can use to indicate that it is not yet ready to receive more data 
and a ‘“‘ready’”’ line that the transmitter can use to notify the receiver that 
data is ready to be sent. 
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The serial method is the one we are more interested in because it is the one 
used by the //c. When this method is used, a byte is decomposed into a series 
of bits and transmitted down one wire only; logical “1’’s and ‘‘O’’s are differ- 
entiated by using a different voltage level for each. Handshaking lines similar 
to those used in a parallel transfer are also often used to control various 
aspects of the communications link. 


The RS-232-C Standard 


There are probably an infinite number of ways that two serial devices can 
be physically connected to permit a useful transfer of information to take 
place. Even so, it is very desirable that a standard method be used so that 
any serial device can communicate with any other, even if the devices are 
manufactured by different companies. 


The Electronics Industries Association published its now famous RS-232-C 
standard in 1969 in an attempt to define a common hardware protocol to be 
used for serial data communications. (“RS-232-C”’ stands for “‘recommended 
standard number 232, revision C.’’) This standard defines the functions of the 
electrical signals that are permitted to be sent from one serial device to 
another, the voltage levels of these signals, and even the physical connectors 
that must be used. The //c does not rigidly adhere to the RS-232-C standard, 
but the differences will not normally prevent you from communicating with 
most serial devices that do. 


Data Communications Protocols for Serial 
Communications 


Even if the hardware link between two serial devices has been properly set 
up, the devices will still not be able to understand each other unless they both 
use the same protocol for exchange of data. 


Such a protocol will first define a transmission speed which is to be used 
for sending and receiving the serial bit stream. The speed is called the baud 
rate and, for most purposes, is simply equal to the number of bits transmitted 
per second. Common baud rates for modems are 110, 300, and 1200. Serial 
printers like the Apple Imagewriter operate at 9600 baud. 


The protocol will also define the following key factors: 

@ The character encoding scheme (ASCII, EBCDIC, Baudot) 
The method used to synchronize the data flow 

The number of data bits 


The order in which data bits are transmitted 


The error-checking method used (parity, checksum) 
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The protocol that is usually used on microcomputers to transmit data to 
another serial device is the one shown in Figure 11-1. This method involves 
the transmission (for each byte to be sent) of a stream of bits in the following 
order (common values are given in parentheses): 


@ One start bit 

@ The data bits (5, 6, 7, or 8) 

@ An optional parity bit (even, odd, mark, space) 

@ The stop bit or bits (1, 1.5, 2) 

The number of data bits, the parity, and the number of stop bits are said 
to define the ‘‘data format” of the transmission. The serial receiver and trans- 


mitter must be using the same data format in order for a successful commu- 
nications link to be established. 


MARK 


‘oof [vee 
SPACE 
start data bits parity stop bits 
bit n=5,6,7,or8 bit 1, 1.5, or 2 
(even, odd, 
mark, space 
or none) 
data flow 


Figure 11-1. The asynchronous serial character transmission protocol... 


Let’s take a closer look at this protocol right now. 


Start Bit 


The transmit line is normally kept at a ‘‘mark”’ level (logic “1”) until a 
character is ready to be sent. A “‘start bit” is then sent by changing the transmit 
line to a ‘‘space’”’ level (logic ‘@’’) for one bit time; this start bit acts as a signal 
to the receiver that the data bits for one character are about to follow. When 
an asynchronous transmission method (such as the one we are discussing) is 
being used, the receiver must be able to recognize when each character being 
sent and it is the use of a start bit that allows it to do so. 


Data Bits 


After the start bit has been sent, the actual data bits are transmitted, one 
by one, at the rate dictated by the baud rate. Bit 0 of the byte being transmitted 
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is sent first, then bit 1, bit 2, and so on. The number of data bits which are 
sent will depend on the particular data format being used by the two serial 
devices; it normally ranges from 5 to 8 bits. When ASCII codes are being 
transmitted, 7 or 8 bits are sent; if binary data bytes are being sent, 8 bits 
must be sent. 


Parity Bit 


Once all the data bits have been sent, a parity bit will be sent if the data 
format being used requires it. There are four different types of parity schemes 
that can be used: 


@ Mark parity (always 1) 
@ Space parity (always 0) 
@ Even parity 
® Odd parity 


If mark or space parity is being used then the parity bit is always fixed to 
1 or 0, respectively. If even parity is used, then the parity bit is adjusted so 
that the total number of ‘‘1’’s in the data bits and the parity bit is an even 
number. When odd parity is used, the adjustment is made so that the total 
number of “‘1"’s is odd. For example, if the data bits being sent are represented 
by 10100011’, and you are using odd parity, the parity bit would be set to 
1; this provides an odd total of ‘1’’s (five). 


A parity bit is inserted into the bit stream to permit the receiver of the data 
to determine if a transmission error occurred. If the receiver is using the same 
data format as the transmitter and an incorrect parity bit is received, then 
the bit stream must have been inadvertently garbled. Such errors invariably 
arise from noise and electrical interference. The parity method of checking 
for errors is certainly not foolproof, however, since multiple bit errors could 
easily cancel each other out. Far more elaborate methods must be used if you 
want to ensure that the data received is, indeed, the same as the data trans- 
mitted. 


Stop Bits 


To indicate the end of the transmission of the data byte, the transmitter 
sends one or more stop bits to the receiver. These stop bits are equivalent to 
“1” bits in that the transmitter signal is kept in the mark state. The number 
of stop bits sent will depend on the data format agreed upon between trans- 
mitter and receiver. The most common values are 1, 1.5, and 2. After the stop 
bits have been sent, the transmitter will stay in the marking state until the 
next data byte is ready to be sent. 
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There are three general classes of errors that a receiver of data can easily 
detect: 


@ Framing errors 
® Overrun errors 


@ Parity errors 


Framing errors occur when the receiver fails to detect a stop bit when it 
expects one. This type of error usually occurs when the receiver and trans- 
mitter are not using the same data format or baud rate. 


Overrun errors occur when a data byte that is received by a serial device is 
not read by the microcomputer that controls that device before another byte 
arrives. 


Parity errors occur if the parity bit that is received is not consistent with 
the data bits that have been read. If parity errors consistently occur, then the 
transmitter and receiver are probably using different baud rates or data 
formats. If they occur occasionally, then they are probably due to transmission 
noise that has scrambled the bit stream. 


The 6551 ACIA 


Each serial port on the //c is controlled by a complex integrated circuit 
called a 6551 ACIA (Asynchronous Communications Interface Adapter). The 
main functions that the 6551 performs are as follows: 


® Parallel to serial conversion of outgoing data 
® Serial to parallel conversion of incoming data 
@ Handshaking control 


@ Interrupt handling 


When you want to send a byte out the serial interface, all you need do is 
present it to the 6551. The 6551 automatically converts the parallel data (the 
byte) into a serial bit stream and frames it by adding the start bit, the proper 
number of stop bits, and the proper parity bit. The 6551 also takes care of 
transmitting the bits at the proper baud rate. 


A block diagram of the 6551 is shown in Figure 11-2. This diagram shows 
the correspondence between the various I/O lines on the 6551 and the pins on 
the DIN-5 port connector on the back panel of the //c. Three-character mne- 
monics are used to refer to the transmit, receive, and handshaking lines used 
by the 6551. These mnemonics come from the RS-232-C standard and have 
the following meanings: 
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data 


keyboard strobe (port 2 
lines y (P 


external interrupt (port 1) 


DIN-5 connector 


to on back panel 
6502 (looking in) 
IRQ 


GROUND 


Recommended pin connections to RS-232-C equipment: 


FROM TO 


DIN-5 signal | Modem (DCE) | Printer (DTE 


RTS (pin 1) DTR (20) DSR (6) 
TXD (pin 2) TXD (2) RXD (3) 
GND (pin 3) | GND (7) GND (7) 
RXD (pin 4) RXD (3) TXD (2) 
DCD (pin 5) DSR (6) DTR (28) 


NOTE: The pin numbers given for DCE and DTE refer to pins on the DB-25 connector defined by 
the RS-232-C standard. 


Figure 11-2. Block diagram of the 6551 ACIA. 


TXD—Transmit Data 
RXD—Receive Data 
RTS—Request to Send 
CTS—Clear to Send 
DTR—Data Terminal Ready 
DSR—Data Set Ready 
DCD—Data Carrier Detect 


The //c is a member of a class of devices that the RS-232-C standard calls 
data terminal equipment (DTE). DTE devices are usually the primary sources 
or destinations of data in a communications link; common DTE devices are 
terminals and printers. The other class of devices defined by the RS-232-C 
standard is called data communications equipment (DCE). DCE devices are 
usually data-link intermediaries that are responsible for maintaining a con- 
nection and passing data between two DTE devices. A modem is the standard 
example of a DCE device. 


The RS-232-C signals on both DTE and DCE are labeled from the point of 
view of DTE only. For example, a DCE device does not transmit data on its 
TXD line; rather, data is transmitted to it (from a DTE device) on that line. 
Similarly, a DCE device does not receive data on the RXD line; in fact, the 
DTE device receives data from the DCE device on that line. 
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DTE devices are usually connected to DCE devices by an electrical cable 
that simply connects each line on the DTE to the corresponding line on the 
DCE, However, when two DTE devices are being connected (such as the //c 
and a serial printer), you can't do this because both devices would be sending 
information on the very same lines. To enable two DTEs (or two DCEs) to 
communicate properly, you have to cross some wires so that one device’s 
output lines are connected to the other's input lines. Here is an example of 
one wire-crossing scheme that is commonly used: 


TXD — RXD 

RXD— TXD 

RTS— CTS 

CTS — RTS 

DSR — DTR 

DTR— DSR 

DCD — DCD (unaffected) 


This crossing of wires can either be done inside the RS-232-C cable itself 
(Apple has done this with its Imagewriter printer cable) or by attaching a 
special device called a “modem eliminator” or a ‘null modem” to a standard 
cable. 


Let's take a look at each of the RS-232-C signals used by the 6551 right now 
and see how they are used to communicate with modems (or any other DCE 
device) and printers (or any other DTE device). 


TXD. The TXD signal is a 6551 output. It is connected to a modem’s TXD 
line or a printer’s RXD line. The serial bit stream is sent down this line to the 
remote device. 


RXD. The RXD signal is a 6551 input. It is connected to a modem’s RXD 
line or a printer’s TXD line. The 6551 monitors this line in order to read the 
incoming serial bit stream. 


RTS. TheRTS signal is a 6551 output. It is usually connected toa modem’s 
RTS line or a printer's CTS line, but on the //c it is meant to be connected to 
the external device's DTR (modem) or DSR (printer) line instead. The remote 
device monitors the status of this line and will not send data to the 6551 until 
it is in a low (O) state. 


CTS. TheCTS signal isa 6551 input. It is supposed to bea signal originating 
from a modem’s CTS line or a printer’s RTS line to indicate that the external 
device is ready to receive data. However, on the //c, the CTS line is not 
connected to the DIN-5 plug and is always kept in a low voltage (@) state. 


DTR. The DTR signal is a 6551 output. It is usually connected to a modem’s 
DTR line or a printer’s DSR line to indicate that the power to to 6551 is on 
and that it is functioning properly. On the //c, however, the DTR signal is not 
used. 
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DSR. The DSR signal is a 6551 input. It is usually connected to a modem’s 
DSR line or a printer’s DTR line so that the 6551 can detect whether the 
remote device is powered up and ready to receive data. On the //c, however, 
the DSR input on serial port 2 is connected to the //c’s keyboard strobe signal 
and, on serial port 1, to one of the input lines on the external disk drive 
connector. These connections have been made to allow a 6551 interrupt signal 
to be generated by the keyboard or by a device connected to the disk drive 
connector (although the add-on disk drive for the //c currently does not use 
this signal). We will be discussing 6551 interrupts at the end of this chapter. 


DCD. The DCD signal is a 6551 input. It is primarily used with modems to 
indicate whether a proper telephone connection has been established with 
the remote computer. If it has, then the DCD input signal will be low (@). For 
the //c, however, Apple has recommended that the DCD input come from a 
modem’s DSR line or a printer's DTR line. If this is done, then the state of 
DCD simply reflects whether the remote device is powered up and ready to 
receive data and does not relate to the state of the telephone connection at 


all. 


The 6551 contains four 8-bit registers that are mapped to locations in the 
/ic’s YO memory space. These registers are used to control various aspects of 
the communications link to devices that are attached to the serial ports. Let's 
look at each of them now and see how they are used. 


6557 Control Register 


The control register is a write-only register that is used to set the following 
communications parameters: 

@ The baud rate 

® The number of data bits (word length) 

@ The number of stop bits 


@ Whether an internal clock or external baud rate clock is to be used (The 
/ic does not support the external clock option.) 


The address of the port 1 control register is $CO9B; the port 2 control register 
is found at $COAB. The meanings of each of the bits in the control register are 
shown in Figure 11-3. 


For example, to set up port | for a baud rate of 1200 baud, a word length 
of 8 bits, and one stop bit, you would execute the following instructions: 


LDA #$18 
STA $C89B 


This sets up a bit pattern of 00011000 in the control register. You can see 
by examining Figure 11-3 that this is the pattern required for this configu- 
ration. 
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5 


7 6 4 3 2 1 0 
ACS 
L__{—_j__j__ 


BAUD RATE (BR): 
000 0 16x External piock 
0620 1 au 
RECEIVER 0010 75 baud 
CLOCK SOURCE 9 9 1 1 109.92 baud 
(RCS): 010 0 13458 baud 
® = external 010 1 150 baud 
1 = internal 011 0 300 baud 
011 1 600 baud 
10 0 0 1200 baud 
100 1 1800 baud 
101 0 2400 au 
ATH WL): 1011 3800 baud 
110 0 4800 baud 
00 8 bits 110 1 7200 baud 
at pea 111 0 9600 baud 
17 opts 11 1°21 += «19200 baud 
STOP BIT NUMBER (SBN): 
®@ = 1 stop bit 
1 = 2 stop bits 
= 1.5 stop bits 
(for WL =5 and no parity) 
= 1 stop bit 


(for WL =8 and parity) 


1/0 address: $C@9B (port 1) 
$COAB (port 2) 


Figure 11-3. The 6551 control register. 


6551 Command Register 


The command register can be used to control the operating modes of the 
6551 as well as the parity bit of the data being transmitted. It is located at 
$CQ9A for port 1 or $C@AA for port 2. The meaning of each bit in the command 
register is summarized in Figure 11-4. 


You can control the state of two handshaking lines on the serial interface 
using the 6551 command register: DTR and RTS. As we saw in the previous 
section, the DTR signal is not connected in the //c implementation of the 6551; 
nevertheless, it must be set low before the 6551 will operate properly. This 
can be done by storing a 1 in bit @ of the 6551 command register. The RTS 
signal must also be set low in normal operating modes; if it is set high, the 
remote device will not send any data to you. 


The command register can also be used to enable or disable transmitter 
and receiver interrupts. For example, if bit 1 is @, then whenever the 6551’s 
receiver register is full (that is, data has arrived and is ready to be read), a 
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7 6 5 4 3 2 1 0 
Tewcr[ pwce [| pwe[ vem [mm [ ve | wo [om 
DATA TERMINAL 
READY (DTR): 


PARITY MODE = 
CONTROL: RECEIVER p TR gt) 
® 0 odd parity ECHO MODE 1 = ready 
@ 1 even parity (REM): (DTR low) 
1 @® mark parity ®@ = normal 
1 1 space parity ‘= echo INTERRUPT REQUEST 
DISABLED (IRD): 
® = enable receiver 
interrupts 
1 = disable receiver 
PARITY MODE interrupts 


ENABLED (PME): 

@ =Nno parity bit 

1 =parity bit(s) used 
TRANSMITTER INTERRUPT 
CONTROL (TIC): 


®@ @ RTS high/no xmit interrupt 
®@ 1 RTS low/xmit interrupt 

1 0 RTS low/no xmit interrupt 

\/Oaddress: $CQ9A (port 1) 1 1 RTS low/no xmit interrupt 
$COAA (port 2) [transmit break signal] 


Figure 11-4. The 6551 command register. 


65C02 IRQ interrupt will be generated. A similar interrupt will be generated 
when the transmitter register is empty (that is, the 6551 is ready to send data) 
if bits 3 and 2 are set to @ and 1, respectively. We will be discussing 6551 
interrupts in greater detail at the end of this chapter. 


6557 Status Register 


The 6551 status register is located at $C099 (port 1) and $C@A9 (port 2). 
This register can be examined to determine the status of various 6551 func- 
tions and to detect whether receiver errors have occurred. The meaning of 
each bit in the status register is summarized in Figure 11-5. 


The status register is most often used to determine when it is possible to 
read incoming data or send outgoing data. For example, if you want to send 
data out the serial port, you would wait until the transmitter data register is 
empty (it’s empty when bit 4 of the status register is 1) and then store the 
data in the data register (see below). Similarly, you can read incoming data 
by waiting until the receiver data register is full (it’s full when bit 3 of the 
status register is 1) and then reading the data from the data register. 
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| 
PARITY ERROR 


@ =n0o error 
1 = error 


FRAMING ERROR 


@ =no error 
1 = error 


OVERRUN ERROR 


@ =Nno error 
1 = error 


RECEIVER DATA 
REGISTER FULL 
@ = not full 

1 = full 


TRANSMITTER DATA 
REGISTER EMPTY 

@ =not empty 

1 =empty 


DATA CARRIER DETECT 


®@ = DCD low (detected) 
1=DCD high (not detected) 


DATA SET READY 
@ = DSR low (ready) 
1 = DSR high (not ready) 


INTERRUPT 
@ =no interrupt 
1 = interrupt occurred 


1/0 address: $C@99 (port 1) 
$C@A9 (port 2) 


Figure 11-5. The 6551 status register. 


The status register can also be used to monitor the states of two incoming 
handshaking lines, DCD and DSR, which were described earlier. Briefly, the 
state of the DCD line can be tested to determine whether the remote device 
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is ready to receive data; if it is, then DCD will be low (that is, bit 5 of the 
status register will be @). The DSR bit can be examined to determine the state 
of the keyboard strobe (port 2 only) or the external interrupt line (port 1 only). 
We'll be examining these signals in detail at the end of the chapter. 


You can also check the status register to determine whether a 6551 interrupt 
condition has occurred. When an interrupt occurs, bit 7 of the status register 
will be 1. 


6551 Data Register 


The data register is located at $C098 (port 1) and $CO@A8 (port 2). This is 
where you store bytes that you want to send out the serial port and also where 
you read incoming bytes. 


The data register should only be read when the receiver data register is full 
and only be written to when the transmitter data register is empty. The states 
of the receiver and transmitter data registers can be determined by examining 
the relevant bits in the 6551 status register. 


Configuring the Serial Ports 


The two external serial ports on the //c are identical. This means that, in 
principle, in doesn't really matter which port an external serial device is 
connected to. However, you have a choice of two built-in firmware subroutines 
to control usage of each port. These subroutines are used to configure a serial 
port as either a printer port or a communications port. 


When you are communicating with a device like a printer that can receive, 
but not transmit, data, then the serial port to which it is connected should be 
configured as a printer port. When this is done, several special commands 
become available that can be used to adjust parameters that affect the data 
sent to a printer. 


On the other hand, if you are communicating with a device that can both 
receive and transmit data, then the serial port should be configured as a 
communications port. Such devices include other personal computers, modems, 
and terminals. 


When the //c is first turned on, serial port 1 is automatically configured as 
a printer port and serial port 2 as a communications port. Although it is 
possible to change this configuration (keep reading to find out how), it is a 
good idea to always connect a printer to port 1 and a modem (or other two- 
way communications device) to port 2. 


We're now going to take a closer look at the characteristics of a printer port 
and a communications port. In the examples which follow, we will assume, 
for convenience, that port | is the printer port and port 2 is the communica- 
tions port. 
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Characteristics of a Printer Port 


When the //c is first turned on, it automatically configures serial port 1 as a 
printer port having the following characteristics: 


@ A baud rate of 9600 
e A data format of 8 data bits, no parity, 2 stop bits 


@ An 8@-column line width (This means that a carriage return character is 
automatically printed whenever 8@ characters are printed without an 
intervening carriage return.) 


@ A line feed character is sent after every carriage return character 


If you don't like these parameters, you can select different ones by using 
special printer commands that we'll be looking at shortly. 


All you have to do to direct character output to a port 1 printer is to enter 
a PR#1 command from the keyboard or to execute the following Applesoft 
statement: 


PRINT CHR$C4);"PR#1" 


from within an Applesoft program. You can use the PR#@ or PR#3 command 
after everything has been printed to direct output to the video display once 
again. 

Once printer port 1 has been turned on with a PR#1 command, there are 
several commands that can be sent to the printer port firmware to modify 
the printer port characteristics. These commands, and the functions they 
perform, are summarized in Table 11-1. These commands can be entered by 
typing them in from the keyboard or by using the Applesoft PRINT command 
to send them directly to the printer port. 


To select a printer command, you must first enter.a special command prefix 
character, followed by the command itself. The default command prefix char- 
acter is [control-I], but this can be changed to another control character by 
entering the current prefix character followed by the new one. You will want 
to do this in situations where it is necessary to send the prefix character itself 
to the printer without it being eaten by the firmware. 


For example, if the current command character is [control-I] and you want 
to change it to [control-K], you would type (or print) the two characters 


Ccontrol-IJ] (Ccontrol-K] 


Note that you must not change the prefix character to [control-A], [control- 
C], [control-H], [control-J], [control-L], [control-M], or [control-Y]. These 
control characters are used for special purposes by the //c’s firmware. 


Let's look at a couple of examples of how to enter printer commands. 
Suppose your printer operates at 1200 baud and that it automatically advances 
the paper after it receives a carriage return code. You will not be able to 
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Table 11-1. Printer port commands. 


Command Description 
nnn Set the new line width to nnn (1... 255). Follow this com- 
mand with [return] or N. 
nnB Set the baud rate to the value corresponding to the nn code: 
Baud Baud 


nn Rate = nnn Rate 


1 50 (9 1800 
2 75 10 2400 
3 110 11 3600 
4 135 12 4800 
5 150 13 7200 
6 300 14 9600 
7 600 15 19200 
8 1200 
nD Set the data format to the value corresponding to the n code: 
Data Stop 
n Bits’ Bits 
0 8 1 
1 1 
2 6 1 
3 5 1 
4 8 2 
5 7 2 
6 6 2 
7 5 2 
I Send printer output to the video screen as well. 
K Don't automatically send a line feed character after every 


carriage return character. If your printer is double spacing 
all output, then you must enter this command. 


L Automatically send a line feed character after every carriage 
return character. If your printer is not advancing the paper 
after the printing of each line, then you must enter this com- 


mand. 
nnnN Set the new line width to nnn (1... 255) and don’t send printer 
output to the video screen. 
nP Set the parity to the state corresponding to the n code: 
n Parity 
Q0,2,4,6 None 


1 Odd (continued) 
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Table 11-1. Printer port commands (continued). 


Command Description 


3 Even 
5 Mark (1) 
7 Space (0) 


R Reset the 6551 ACIA and turn off the printer port. 


S Send a 233 millisecond break signal to the printer. This signal 
is used to synchronize some printers with the serial output 
stream. 


Z Ignore further command characters until the next PR#1 or 
[control-RESET]. Disable the automatic insertion of carriage 
return characters. 


communicate with this printer right after the //c is turned on because the 
default baud rate is 9600 baud. To fix this up, enter PR#1 from Applesoft 
direct mode and then enter the command: 


Ccontrol-I] 8B 


As soon as you enter [control-I] you will see a question mark prompt begin 
to flash; after you enter the ‘‘8B” command to set the baud rate to 1200 it will 
disappear. You can now send data to the printer in the normal way. Your 
problems are not over, however, because all your output will be double 
spaced. This happens because the printer automatically advances the paper 
one line after it receives a carriage return code but it advances it one more 
line in response to the line feed code that the //c automatically inserts after 
every carriage return. To disable the line feed insertion, enter the command: 


Ccontrol-I] K 


and everything will work fine. 


You could also have entered the printer commands by using the Applesoft 
PRINT command within a program. Here is a line that you could execute to 


do this: 
1808 PRINT CHR$C4);"PR¥1": PRINT CHRS$C9);"8B" 


sCHR$C9);3"K': 
Characteristics of a Communications Port 


Serial port 2 is automatically configured as a communications port when 
the //c is first turned on. The initial characteristics of that port are as follows: 
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@ A baud rate of 300 
e A data format of 8 data bits, no parity, 1 stop bit 


@ A line feed character is not automatically inserted after each carriage 
return character. 


@ Output is not displayed on the video screen. 


Once a communications device has been attached to port 2, you can tell the 
//c to get character input from it (or from the keyboard) by entering the IN#2 
command. Similarly, you can send character output to it by entering the 
PR#2 command. After you enter an IN#2/PR#2 sequence like this, the //c is 
said to be in remote-control mode; in this mode the remote device has com- 
plete control over the //c and its operator can load and run programs, catalog 
the disk, and so on, in the very same way that the operator of the //c can. 


You've got to be a little careful if both the IN#2 and PR#2 commands are 
active at the same time, however. In this situation, all input from the remote 
device will be echoed back to it. This is fine unless the external device is also 
echoing its input; if this is the case, the //c and the remote device will begin 
to play volleyball with the first character transmitted from either end. Use 
the [control-RESET] panic button to recover control if this happens. 


The commands supported by the communications port include all those 
defined by the printer port and two more that are needed to use a special 
terminal mode that we'll discuss below. These additional commands are 
summarized in Table 11-2. ‘ 


The communications port commands can only be entered after a PR#2 or 
IN#2 command has been entered and each must be preceded by a special 
command prefix character, [control-A]. Except for the ‘“‘nnn’’ command, it is 
not necessary to press [return] after entering a command from the keyboard. 


You can change the communications port prefix character using the same 
method used to change the printer port prefix character. For example, to 


change the prefix from [control-A] to [control-E], you would enter the com- 
mand: 


Ccontrol-AJ [Ccontrol-E] 


You should note, however, that the prefix should not be changed to [control- 
B], [control-C], [control-H], [control-I], [control-J], [control-L], [control-M], 


or [control-Y]. These control characters are reserved for use by the //c’s firm- 
ware. 


Terminal Mode 


We've just seen that the communications port supports two extra com- 
mands that relate to something called terminal mode. Terminal mode is just 
a fancy name for a short program in the //c’s firmware that permits the //c to 
have a dialog with the remote device without interfering with Applesoft or 
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ProDOS. While you are in terminal mode, the characters that you type in or 
that are sent to you by the remote device are displayed on the screen but are 
not passed through to the underlying operating system. 


To get into terminal mode, first activate remote control mode by entering 
IN#2 (followed by PR#2 if you want to echo all input to output), and then 
enter [control-A] T. When terminal mode is active, a blinking underline cursor 
will appear and you can begin to converse with the remote device by typing 
in messages from the keyboard. Since these messages are not passed through 
to Applesoft or ProDOS, you can type in anything you want and you will not 
see an Applesoft PSYNTAX ERROR message or overwrite the program in 
memory. 


To exit terminal mode, you can either enter [control-A] Q from the //c’s 
keyboard or wait for a [control-R] to be sent by the remote device. The remote 
device can also pop the //c back into terminal mode from remote-control mode 
by sending a [control-T] character. 


Changing the Default Configuration 


The default configurations for the two serial ports are defined by two sets 
of four bytes in the //c’s ROM. When the //c is first turned on, these bytes are 
transferred to screen holes in auxiliary memory; they are read from here 
whenever a Serial port is activated with a PR# or IN# command. The locations 
used to store the configuration bytes for each port and a functional description 
of each byte can be found in Table 11-3. 


The first two bytes in each quartet contain the values that must be stored 
in the 6551’s control and command registers in order to select the desired 
baud rate and data format. 


Three bits in the third byte are used as flags to set whether the port is to 
send output to the video display as well as the external serial device, whether 
it is to automatically insert line feeds after carriage returns, and whether the 
port is a communications port or a printer port. 


The last byte holds the printer width byte and will normally be zero for a 
communications port. 


You can easily redefine a port’s default configuration by storing the appro- 
priate values in the auxiliary memory screen holes. For example, if you want 
port 1 to be configured as a communications port when it is initialized, just 
store a byte at $47A that has bit @ equal to 1. This configuration change will 
persist until the //c’s power is turned off, even if another diskette is booted. 


When changing the configuration bytes you must keep in mind that it is 
bytes in auxiliary memory, not main memory, that must be accessed. To 
change these bytes you will have to write a small program that first throws 
the 80STOREON ($CQ@01) switch, turns on auxiliary memory by writing to 
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Table 11-3. Configuration bytes used by the serial ports. 


Location 

Hex (Dec) 
$478 (1144) 
$479 (1145) 
$47A (1146) 
$47B (1147) 
$47C =(1148) 
$47D = (1149) 
$47E (1150) 
$47F (1151) 


Description 


Port 1: Contents of 6551 control register 
(Default = $9E: 8 data bits, 2 stop bits, 9600 
baud) 


Port 1: Contents of 6551 command register 
(Default = $0B : no parity) 


Port 1: Flags 
(Default = $40: no echo, LF after CR, printer 


port) 
Bit Bit = 1 means... 
7 Echo output on video screen. 
6 Insert line feed after carriage return. 
5-1 [not used] 
0 Configure as a communications port (@ = 


configure as a printer port). 


Port 1: Number of non-carriage-return characters to 
send before automatically sending a carriage 
return (‘printer width”). If zero, then don’t 
insert carriage returns. (Default = $50 : 80 
columns) 


Port 2: Contents of 6551 control register (Default = $16 
: 8 data bits, 1 stop bits, 300 baud) 


Port 2: Contents of 6551 command register (Default = 
$QB : no parity) 


Port 2: Flags 
(Default = $01 : echo on, no LF after CR, 
communications port) 


Bit Bit = 1 means... 
7 Echo output on video screen.. 
6 Insert line feed after carriage return. 
5-1 [not used] 
0 Configure as a communications port (@ = 


configure as a printer port). 


Port 2: Number of non-carriage-return characters to 
send before automatically sending a carriage 
return (“printer width’). If zero, then don't 
insert Carriage returns. 

(Default = $0@ : no CR insertion) 


Note: All locations are in the auxiliary memory screen holes. 
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PAGE2ON ($C@55), POKEs the new configuration bytes into the screen holes, 
and then re-enables main memory by writing to PAGE2OFF ($C@54). An 
example of such a program is given in Table 11-4. This program configures 
port 1 as a 1200 baud communications port and sets up a data format of 8 
data bits, no parity, and one stop bit. 


Table 11-4. CHANGE.PORT—a program to change the default 
configurations of the //c’s serial ports. 


9 REM “CHANGE.PORT* 

1 REM THIS PROGRAM CHANGES THE 
2 REM STARTUP CONFIGURATION OF 
3 REM SERIAL PORT 1 OR 2 


168 PN = 1: REM SERIAL PORT 1 
118 AD = @: IF PN = 2 THEN AD = 
4 


12@ POKE 49153,0: REM 8@STOREON 


138 POKE 49237,0: REM SELECT AU 
XILTARY MEMORY 
1490 POKE 1144 + AD,24: REM 8SN1, 
1208 BAUD 
158 POKE 1145 + AD,11: REM NO P 
ARITY 
168 POKE 1146 + AD,1: REM COMM. 
PORT 
178 POKE 1147 + AD,@: REM NO CR 
INSERTION 
188 POKE 49236,0: REM SELECT MA 
IN MEMORY 


6551 Interrupt Handling 


The 6551 ACIA can also be programmed to generate 65C@2 IRQ interrupts 
in the following situations: 


@ When the receiver register is full 

@ When the transmitter register is empty 

@ When the DCD line changes state 

@ When the DSR line changes state 

These interrupts will be recognized and acted upon by the 65C@2 only if 


the interrupt flag in the processor status register is @. This condition can be 
forced by executing a CLI (clear interrupt) instruction. 
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To permit the 6551 to generate interrupts, you must always ensure that its 
DTR line is in a low state. This can be done by storing a 1 in bit 0 of the 6551 
command register. In addition, you must store a @ in bit 1 of the command 
register to enable receiver interrupts, or a @ in bit 3 and a 1 in bit 2 of the 
command register to enable transmitter interrupts. (The DCD and DSR inter- 
rupts cannot be selectively disabled and enabled.) When an interrupt occurs, 
bit 7 of the status register will be set to 1. 


We saw in Chapter 1@ that the //c’s ROM contains a complex interrupt- 
handling subroutine that is responsible for managing mouse and VBL inter- 
rupts. It’s no surprise, then, to learn that it also contains an equally complex 
subroutine to handle interrupts emanating from the serial ports. 


The //c will either handle the serial interrupt internally or will pass it along 
to your own interrupt-handling subroutine. It decides what to do with an 
interrupt by examining the types of serial interrupts that have been enabled 
and the contents of special flag bytes stored in the screen holes of the //c’s 
main memory space. A flowchart of the //c’s internal interrupt- handling 
subroutine is shown in Figure 11-6. 


6557 Transmitter Interrupts 


Transmitter interrupts are enabled by storing a @ in bit 3 and a 1 in bit 2 
of the 6551 command register. After this has been done, the 6551 will generate 
an interrupt whenever the transmitter data register becomes empty. 


Transmitter interrupts are never serviced by the //c’s internal interrupt 
handler and are always passed through to the one that you have installed. In 
fact, if transmitter interrupts are enabled, all 6551 iriterrupts are passed 
through. 


You can clear a transmitter interrupt condition by reading the 6551 status 
register. 


6557 Receiver Interrupts 


Receiver interrupts are enabled by storing a @ in bit 1 of the 6551 control 
register. When this is done, the 6551 will cause an interrupt whenever the 
receiver data register becomes full. 


The //c’s internal serial interrupt handler will always pass through receiver 
interrupts to your own interrupt handler if transmitter interrupts have also 
been enabled. If transmitter interrupts have not been enabled, however, receiver 
interrupts will only be passed through if the value stored at ACIABUF ($4FF) 
is not equal to $Cn, where “‘n”’ is the number of the serial port that caused 
the interrupt (1 or 2). 


If ACIABUF does contain $Cn, then the //c services the interrupt by reading 
the 6551 data register and placing the data in a 128-byte receiver buffer that 
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xmit 
interrupts 
enabled? 


YES 


6551 
interrupt? 


If port 1, 
invert the ————p» 
DSR bit. 


NO 


Put serial 
data in 
buffer. 


TYPEHED 


ACIABUF 
7 = $Cn? 
bit 6 = 17 


TYPEHED 
bit 7 = 0? 


Put keyboard : 
data in 


CLC 
buffer. 


or 
port 1 


Put DSR bit 
in carry 
flag. 


Receiver 
Full? 


Receiver 
interrupts 
on? 


NO 


TYPEHED = $5FA (port 2), $5FB (port 1) 
ACIABUF = $4FF 


Keyboard Buffer: $880. . . $8FF (aux. memory) 
Serial Buffer: $800. . $87F (aux. memory) 


To read serial buffer, call XRDSER ($C835) with Y=9. If data is present, the carry flag will 
be set and the data will be in A. 


Onexit: If carry flag is set, interrupt passes through. 
If carry flag is clear, interrupt is serviced internally. 


Figure 11-6. A flowchart of the internal interrupt handler that services 6551 
serial interrupts. 


is located from $800 ...$87F in auxiliary memory. This buffer can be read 
by calling the XRDSER ($C8C5) subroutine with the Y register set to 0 or by 
reading from the serial port firmware (assuming that the appropriate IN# 
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command is active). On exit from this subroutine, the carry flag will be clear 
if the buffer is empty; if it isn't, then the carry flag will be set and the character 
will be in the accumulator. 


If a receiver interrupt is passed through, the interrupt must be serviced by 
reading the 6551 status register. Remember that a receiver interrupt will be 
passed through if it occurs when ACIABUF ($4FF) contains a value other than 
$C1 or $C2. 


The receiver interrupt is probably the most useful type of interrupt that the 
6551 supports, at least as far as the //c is concerned. Why? Because at baud 
rates of 1200 or higher, the //c is often not capable of polling for serial input 
fast enough to prevent the loss of incoming characters. For example, in the 
time it takes the //c to scroll its full 80-column screen, two or three characters 
may arrive at the serial port. Since the //c’s scrolling subroutine does not poll 
the serial ports while it executes, these characters will be missed. If receiver 
interrupts are enabled, however, these characters can be placed in a buffer 
from which they can be read when the program has the time to handle serial 
input. 


65571 Keyboard (DSR port 2) Interrupts 


The //c makes rather ingenious use of the DSR input lines on its two 6551s. 
The port 2 DSR line is connected to the //c’s keyboard strobe line. As we saw 
in Chapter 7, the keyboard strobe is normally low (@) but goes high (1) when 
a key is pressed on the keyboard. Such a transition will cause a 6551 DSR 
interrupt signal to be generated from serial port 2. 


The //c’s built-in interrupt-handling subroutines can be told to service the 
keyboard interrupt and place the keycode into a 128-byte buffer in auxiliary 
memory (the buffer extends from $880 to $8FF). The //c’s standard keyboard 
input subroutine will, in these circumstances, examine the buffer for presence 
of input; the keyboard I/O location, KBD ($C0@@), will only be polled if the 
buffer is empty. 


Contrast this method of handling keyboard input with the one that is 
traditionally used; the traditional method is to repeatedly scan the keyboard 
strobe line until it goes high and then read KBD ($C00@) to get the keycode. 
This method is called “polling” because the software is continually “asking”’ 
the keyboard whether it has a character available. One consequence of using 
the polling method is that if you try to enter characters from the keyboard 
when the //c is not actually polling the keyboard, then all those characters 
will be ““missed” except for the last one entered. 


The advantage of using the keyboard interrupt technique should be obvious: 
unless the interrupts are turned off by the software (using a SEI instruction), 
all characters entered from the keyboard will be saved in the buffer (assuming 
that it is not full) and will be available to the program even if the program is 
not, at the time of the keypress, reading the keyboard. Thus, you can “type 
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ahead”’ of the program and wait for it to read your already entered input 
later, when it is ready to receive it. 


If you want the //c’s internal serial interrupt-handling subroutines to sup- 
port an interrupt-driven keyboard, then five simple steps must be performed: 


@ Disable 65C@2 interrupts by executing a SEI instruction. 


@ Enable the interrupt handler’s buffering of keyboard data by setting bit 
7 of TYPHED ($5FA) to 1 and bit 6 to @. (This can be done by storing $80 
in $5FA.) 


@ Clear the keyboard buffer by setting locations TWKEY ($5FF) and TRKEY 
($6FF) to $80. TWKEY points to where the next key will be stored and 
TRKEY points to where the next key will be read from. 


® Set DTR low by storing a 1 in bit @ of the 6551 command register at 
$COAA (port 2). 


@ Enable 65C@2 interrupts by executing a CLI instruction. 


The short assembly-language subroutine that does all this looks something 
like this: 

SEI 

LDA #$8@ 

STA $SFA 

STA $SFF 

STA $GFF 

LDA #$61 

STA $COAA 

LDA #$89 

STA $SFA 

CLI 

RTS 


Let’s see if it works. Enter and run the following trivial program after 
executing the preceding subroutine: 


199 FOR I = 1 TO 2000: NEXT 


and then start typing madly away at the keyboard. When the program finishes, 
all the keystrokes that you entered should be displayed after the Applesoft 
prompt symbol! 


By the way, the type-ahead buffer can be cleared (or ‘‘flushed”’) at any time 
by entering [control-X] from the keyboard while holding down the OPEN- 
APPLE key. You may want to flush the buffer in situations where you have 
typed in incorrect characters but the program has not yet used them. 


There is one severe limitation to the type-ahead feature as implemented on 
the //c: it will miss characters that are typed in when the disk drive is being 
used. This is because ProDOS turns off interrupts during all disk accesses in 
order to ensure that time-critical disk I/O subroutines are not disturbed. 
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Keyboard interrupts can either be serviced by the //c’s interrupt-handler or 
your own. The keyboard interrupt will be passed through to you if transmitter 
interrupts are enabled for port 2’s 6551, or if transmitter interrupts are 
disabled and bit 6 of TYPHED ($5FA) is 1. 


If transmitter interrupts are enabled when a keyboard interrupt occurs, 
your interrupt-handling subroutine must service the interrupt by performing 
the following steps: 


@ Read the 6551 status register ($CQA9) to check that the IRQ bit (bit 7) is 
“1” (that is, that the serial port is the source of the interrupt) and that 
the DSR bit (bit 6) is “1” (that is, that the keyboard caused the serial 
interrupt). 


@® Read KBD ($C000) to get the keyboard data and accessing KBDSTRB 
($C@1) to clear the keyboard strobe. 


@ Read the 6551 status register once again to clear the interrupt caused by 
the 1 to 0 transition on the DSR line that occurs when the keyboard 
strobe is cleared. 


If, however, the keyboard interrupt is passed through because bit 6 of 
TYPHED ($5FA) is 1 and transmitter interrupts are not enabled, the interrupt- 
handling subroutine cannot read the 6551 status register to check the state 
of the IRQ bit. This is because the //c’s internal interrupt handler clears this 
bit by reading the status register itself before relinquishing control. Fortu- 
nately, however, it stores a copy of the value read from the status register at 
location $4FA so that it can be examined instead. Before the interrupt-han- 
dling subroutine ends it must clear the interrupt by storing a @ in $4FA. 


6557 External (DSR port 1) Interrupts 


The port 1 DSR line is connected to another line that comes in through pin 
9 on the //c’s external disk drive connector. It is not currently used by the 
standard external disk drive supplied by Apple, and its intended use is still a 
mystery. To enable the interrupt signal that is generated when this line 
changes state, bit @ of the 6551 control register for port 1 ($C@9A) must be set 
to l. 


The //c’s serial interrupt-handler monitors the state of the external DSR 
interrupt line but does not do much with it. If transmitter interrupts are 
enabled for port 1’s 6551, however, or if they’re not but bit 6 of EXTINT2 
($5F9) is 1, the interrupt will be passed on through to your own interrupt- 
handling subroutine so that you can deal with it yourself. 


Note that the //c has been configured in such a way that even if bit 6 of 
EXTINT2 is 1, a port 1 DSR interrupt will only be passed through when high 
(1) to low (@) transitions of the DSR line take place (just the opposite to port 
2). From this we can assume that any device that generates an external 
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interrupt will be expected to keep the interrupt line high and to bring it low 
only when an interrupt occurs. 


The port 2 DSR interrupt can be serviced in the same general way as the 
corresponding interrupt for port 1. First, you must read the status register to 
check the state of DSR and clear the IRQ bit. Then, you must deal with the 
device that caused the interrupt in such a way that its interrupt signal will 
be turned off. (Without knowing what the device is we can’t really say what 
to do.) Finally, the status register must be read once again in order to clear 
the interrupt caused by the reverse transition of the external interrupt line 
after the device turns off its interrupt signal. 


Further Reading for Chapter 11 


On serial communications in general ... 


E.A. Nichols, J.C. Nichols, and K.R. Musson, Data Communications for 
Microcomputers, 1982, McGraw-Hill Book Company. This book describes 
the RS-232-C standard in detail as well as various transmission protocols. 
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65CQ2 Instruction Set and 
Cycle Times 


Instruction 
Mnemonic 


ADC 


ASL 


BCC 
BCS 
BEQ 


Assembler 


Operand Format 


#num 


zZpage 
Zpage,X 


*(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


#num 
zpage 
Zpage,X 


*(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


[accumulator] 
zZpage 
Zpage,X 

abs 

abs,X 


disp 
disp 
disp 


Opcode Number 


Byte 


69 
65 
75 
72 
61 
71 
6D 
7D 
719 


29 
25 
35 
32 
21 
31 
2D 
3D 
39 


OA 
06 
16 
OE 
1E 


90 
BO 
FO 


331 


of Bytes 


NN NY WWNNK WWWNNNNNN WWWNNNN WN WLW 


Number of 
Clock Cycles Notes 


NM NY NY ADAUY HHHAPNNANMAWN HPHNAAMNHAWN 


(1) 


(1) 
(1) 


(3) 
(2) 
(2) 
(2) 


(continued) 
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Instruction 
Mnemonic 


BIT 


BMI 
BNE 
BPL 
BRA 
BRK 
BVC 
BVS 
CLC 
CLD 
CLI 
CLV 
CMP 


CPX 


CPY 


DEA 
DEC 


DEX 


Assembler 
Operand Format 


[implied] 
disp 

disp 

[implied] 
[implied] 
[implied] 
limplied] 


#num 


zZpage 
Zpage,X 


*(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs, Y 


#num 
zpage 
abs 

#num 


zpage 
abs 


*[accumulator] 


zpage 
zpage,X 
abs 
abs, X 


Limplied] 


Opcode 
Byte 


89 
24 
34 
2C 
3C 


30 
DO 
10 
80 
00 
50 
70 
18 
D8 
58 
B8 


C9 
C5 
DS 
D2 
Cl 
D1 
CD 
DD 
D9 


EQ 
E4 
EC 


CO 
C4 
CC 


3A 


C6 
D6 
CE 
DE 


CA 


Number 
of Bytes 


=m WNYWNHNH —&@& WNN WNN WWWNNNNNN | | | KH NN HK VN NN NY WWNHNNY 


Number of 
Clock Cycles Notes 


WwW Anau NY BWH BWH HAPBPVUAMNBWN NY YB NN NN NY ITN NN N HHP HWN 


(2) 
(2) 
(2) 
(2) 


(2) 
(2) 


(1) 


(1) 
(1) 


(3) 


(continued) 


Instruction 
Mnemonic 


DEY 
EOR 


INA 
INC 


INX 
INY 
JMP 


JSR 
LDA 


LDX 


LDY 


Assembler 


Operand Format 


[implied] 


#num 
zpage 
Zpage,X 
*(zpage) 
(zpage,X) 
(zpage),Y 
abs 
abs ,X 
abs, Y 


*laccumulator] 


zpage 
zpage,X 
abs 
abs,X 


[implied] 
[implied] 
abs 


(abs) 
*(abs,X) 


abs 


#num 
zpage 
Zpage,X 
“(zpage) 
(zpage,X) 
(zpage),Y 


Opcode 
Byte 


88 


49 
45 
55 
52 
41 
51 
4D 
5D 
59 


1A 


E6 
F6 
EE 
FE 


E8 
C8 


4C 
6C 
7C 


20 


A9 
AS 
B5 
B2 
Al 
Bl 
AD 
BD 
B9 


A2 
A6 
B6 
AE 
BE 


AO 
A4 
B4 
AC 
BC 


Number 
of Bytes 


WWNWNNMW WWNHNNN WWWNNNNNN W WWW | FF WWNN =| WWWNNNNNN 
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Number of 
Clock Cycles 


No 


BBEDBRWNH BBRAWH HBHRBUDMNBWN BDA DADWN YM ADDU NY HhHAMNDAUWNHWN 
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Notes 


(1) 


(1) 
(1) 


(3) 


(4) 


(1) 


(1) 
(1) 


(1) 


(1) 


(continued) 
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Instruction 
Mnemonic 


LSR 


NOP 
ORA 


PHA 
PHP 
PHX 
PHY 
PLA 
PLP 
PLX 
PLY 
ROL 


ROR 


RTI 
RTS 
SBC 


Assembler 
Operand Format 


[accumulator | 


[implied] 


#num 


zpage 
zpage,X 


*“(zpage) 


(zpage,X) 
(zpage),Y 
ads 

abs,X 
abs, Y 


limplied] 
[implied] 


*(implied] 
*{implied] 


limplied] 
[implied] 


*{implied] 
*“limplied] 


[accumulator] 


zpage 
zpage,X 
abs 
abs,X 


[accumulator] 


zpage 
zpage,X 
abs 
abs,X 


limplied] 
[implied] 


#num 


Zpage 
zpage,X 


Opcode Number 


Byte 


4A 
46 
56 
4E 
SE 


FA 


09 
05 
15 
12 
01 
11 
0D 
1D 
19 


48 
08 
DA 
SA 
68 
28 
FA 
TA 


2A 
26 
36 
2E 
3E 


6A 
66 
76 
6E 
7E 


40 
60 


E9 
E5 
F5 


of Bytes 


NNO = MB WWNONKS WWNON S| | FF YF YE ESF ES ES lhl WWWwWNNNONN NN = WM WN NN 


Number of 
Clock Cycles Notes 


BWN DA DBD AAAUN ADAUN SL HF Hh BWW WwW W HHHUNAMNHWN WLW NAO Udy 


(3) 


(1) 


(1) 
(1) 


(3) 


(3) 


(continued) 


Instruction 
Mnemonic 


SEC 
SED 
SEI 

STA 


STX 


STY 


STZ 


TAX 
TAY 
TRB 


TSB 


TSX 
TXA 
TXS 
TYA 


Assembler 
Operand Format 


“(zpage) 


(zpage,X) 
(zpage),Y 
abs 

abs ,X 
abs, Y 
[implied] 
Limplied] 
[implied] 


zpage 
zpage,X 


“(zpage) 


(zpage,X) 
(zpage),Y 
abs 
abs,X 
abs,Y 


Zpage 
zpage,Y 
abs 


[implied] 
[implied] 


*“zpage 
*abs 


*7page 
“abs 


Limplied] 
limplied] 
[implied] 
[implied] 


Opcode Number 


Byte 


F2 
El 
Fi 
ED 
FD 
F9 


38 
F8 
718 


85 
95 
92 
81 
91 
8D 
9D 
99 


86 
96 
8E 


84 
94 
8C 


64 
74 
9C 
9E 


AA 
A8 


14 
IC 


04 
OC 


BA 
8A 
9A 
98 


of Bytes 


Pe BH WN WN —& & WWNN WNN WNN WWWNNNNN KF EF RH WWWNN DH 
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Number of 
Clock Cycles Notes 


Nm NWN NY AW AN NY NY WUBAW HPW HAW HHAPMNAUHW NY NY NY HSHHPUAUY 


(1) 


(1) 
(1) 


(1) 


(1) 
(1) 


(continued) 
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*Instructions marked with an asterisk are not available on the 6502. 
Notes: 


(1) Add one clock cycle if a page boundary is crossed. 


(2) Add one clock cycle if a branch occurs to a location in the same page; add two 
clock cycles if a branch occurs to a location in a different page. 


(3) Add one clock cycle if a page boundary is crossed; always 7 cycles on the 6502. 
(4) 5 cycles on the 65@2. 


See Table 2-3 for a description of the assembler operand formats. 


Appendix III 


Apple //c Soft Switch, 
Status, and I/O Port 
Locations 


NOTE: The “Usage” column in the following tables indicates how a par- 
ticular location is to be accessed: 


“W” means “write to the location.” 

“R”’ means ‘‘read from the location.” 

“RW” means ‘‘read from or write to the location.” 

“R7” means ‘‘read and check bit 7 to determine the status.” 

¢ ” 6 . . . . ” 
RR” means “read from the location twice in succession. 


The term ‘‘aux.” refers to the auxiliary block of 64K memory and “main” 
refers to the main block of 64K memory. “BSR” refers to the //c’s 16K bank- 
switched RAM space from $D000-$FFFF. 
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Appendix IV 


Apple //c Page 3 Vectors 


Address 
$3D0-$3D2 


$3D3-$3D5 


$3D6-$3EC 
$3ED-$3EE 


$3EF 
$3FO-$3F 1 


$3F2-$3F3 


$3F4 


$3F5-$3F7 


$3F8-$3FA 


Contents 


JMP $BE00 


JMP $BE00 


$FA59 


$BEOO 


$1B 


JMP $BEQ3 


JMP $BE00 


Description 


A JMP instruction to the ProDOS warm- 
start entry point. A call to this vector will 
reconnect DOS without destroying the 
Applesoft program in memory. Use the 
‘““3D0G" command to move from the sys- 
tem monitor to Applesoft. 


A JMP instruction to the ProDOS warm- 
Start entry point. 


[Reserved by ProDOS] 


The address of the subroutine to be called 
by XFER ($C314) is stored here. 


[Reserved by ProDOS] 


The address of the subroutine to which 
control is to be passed when a BRK 
instruction is executed (low-order byte 


first). 


The address of the subroutine to which 
control is to be passed when a RESET 
interrupt is generated (low-order byte first). 


POWERED-UP BYTE. The reset vector at 
$3F2 is used only if the number stored 
here is equal to the logical exclusive-OR 
of the number stored at $3F3 and the con- 
stant $A5. 


A JMP instruction to the subroutine to 
which control is to be passed when the 
Applesoft ‘’&’’ command is executed. 


A JMP instruction to the subroutine to 
which control is to be passed when the 
system monitor’s USER command ([con- 


trol-Y]) is entered. . 
(continued) 
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Address Contents Description 
$3FB-$3FD JMP $FF59 [Reserved by system monitor] 
$3FE-$3FF $BFEB The address of the subroutine to which 


control is to be passed when an IRQ inter- 
rupt is generated (low-order byte first). 


Note: All addresses are stored with the low-order byte first. 


Appendix V 


For Beginners Only 


The purpose of this appendix is to familiarize novice programmers with a 
few of the more important fundamental computer concepts. By mastering 
these concepts before reading the main body of this book, you should be able 
to more easily understand the technical descriptions and programming exam- 
ples that will be presented. 


For more detailed information on these topics, more general books on 
computing should be consulted. Many of the references included at the end 
of each chapter in this book will be useful in this regard. 


Numbering Systems 


We are all familiar with the decimal numbering system that makes use of 
ten fundamental digits. This system, however, is not sacred and we could, if 
we preferred, use other systems that use fewer or more digits. 


When dealing with computers, it is often convenient to use the binary 
numbering system and the hexadecimal numbering system. The binary num- 
bering system uses only two digits, @ and 1. The hexadecimal system uses the 
following sixteen digits: 


0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F 


which represent decimal numbers @ through 15, respectively. 


The 65C@2 microprocessor that controls the Apple //c performs all its inter- 
nal operations using binary numbers because it has available to it thousands 
of logic cells that can easily be turned either ‘‘on” or “‘off’’ to represent the 
binary digits “1” or “@,” respectively. Binary numbers, however, are usually 
not used when writing a program because they are difficult to read and are 
prone to transcription errors. Decimal-number equivalents of binary numbers 
are often used instead, but the pattern of binary ones and zeros to which they 
refer are often not immediately obvious (quick now, what is the binary rep- 
resentation of 225?). The hexadecimal numbering system, however, is an ideal 
alternative because each hexadecimal digit defines exactly one of the sixteen 
four-digit patterns of binary ones and zeros, making conversion between 
binary and hexadecimal very easy. 
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In this book, hexadecimal numbers will be preceded by “$” to distinguish 
them from decimal numbers. They will be used when referring to data values 
or to memory addresses. 


Bit Numbering and “Significance” 


The basic unit of storage in the Apple //c, and most other microcomputers, 
is the byte. As far as the 65C@2 microprocessor is concerned, each byte is 
made up of eight bits, each of which can be either on or off (a computer likes 
things that can exist in only one of two states). This means that binary 
numbers from 00000000 to 11111111 (@ to 255 decimal) can be stored in one 
byte. 


Each bit in a byte is associated with a certain binary weight equal to the 
number that the byte would represent if that bit were on and all the other 
bits were off. These binary weights are as shown in Figure V-1. 


TTT TTS) en 


~««—binary weights 
"Figure Vt. Binary weights ‘of each bit in a byte. 


(Notice that the bits within the byte are numbered from @ to 7 and not from 
1 to 8.) To determine the decimal representation of the bit pattern, it is simply 
necessary to add up the binary weights of all bits in the byte that are on. 
Since bit 7 contributes most, it is called the most-significant bit or ’high- 
order’ bit. Conversely, bit @ is referred to as the least-significant bit or “low- 
order’ bit. 


Bit 7 of a byte is also called the “sign bit” because it is often used to indicate 
whether the number stored in the byte is positive or negative (if it is 1, then 
the number is considered to be negative). The 65C@2 microprocessor that 
controls the //c uses a special internal status register which, among other 
things, holds a flag that represents the sign of any number being dealt with. 
(See Chapter 2.) Special 65C@2 instructions are available that can change the 
flow of a program depending on the state of this sign flag (they are called 
“BPL,’ branch on plus, and “BMI,” branch on minus). The //c uses bit 7 of 
several special memory locations to hold information relating to the state of 
the system. When these status locations are examined in an assembly-lan- 
guage program, BPL can be used to transfer control if the status is off (bit 7 
is ®) and BMI can be used to transfer control if the status is on (bit 7 is 1). The 
same thing can be done from an Applesoft program by using the PEEK 
command to read the number stored at the status location. If bit 7 is on, then 


the value read will be greater than or equal to 128 (since the binary weight 
of bit 7 is 128). 
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Situations where more than one byte is required to store a number (that is, 
the number is larger than 255) are quite common. In these cases, the byte 
that contains information on the highest-weighted bits for the number is 
called the most-significant byte or high-order byte, and the byte that contains 
information on the lowest-weighted bits is called the least-significant byte or 
low-order byte. 


Pointers and Vectors 


In Chapter 2 you will see that the 65C@2 microprocessor is capable of 
controlling a memory space that is mapped to the addresses from 
$0000 ... $FFFF. Since one byte can hold exactly two hexadecimal digits, any 
address in the 65C@2’s memory space can be stored in two bytes. 


A pointer or ‘vector’ is a pair of memory locations that contains the address 
of another location to which the pointer is said to be pointing. The least- 
significant byte of the pair is always stored in the first memory location and 
the other byte in the next higher location. To determine the address stored in 
a pointer, you can use the following Applesoft formula: 


ADDR = PEEKCX)+2S56*PEEKCX+1) 


where X represents the first memory location which the pointer occupies. The 
second byte in the pair is multiplied by 256 since it represents the number of 
256-byte units that make up the address. 


The 65C@2 microprocessor makes extensive use of pointers to access data 
arrays and to handle interrupts. (See Chapter 2.) Applesoft also maintains a 


great many pointers for keeping track of its many data areas. (See Chapter 
4.) 


Control Characters 


Control characters are special characters that are entered from the key- 
board by using the CONTROL key. Although they do not represent visible 
symbols, they often cause the //c to perform special functions. Such characters 
will be denoted in this book by [control-X], where X refers to any alphabetic 
character (A... Z) or one of the following special symbols: @ [\ ] “ _. The 
CONTROL key acts just like another SHIFT key in that it and one other key 
must be pressed at the same time in order to enter a control character from 
the keyboard. The procedure involves first pressing the CONTROL key and 
then, while still holding it down, pressing the other key (‘‘X” in the above 
example). 


65C02 Assembly Language 


Many of the programs presented in this book are written in a programming 
language that can be used to generate a series of bytes (which represent 
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microprocessor instructions and data) that can be interpreted and directly 
executed by the //c’s 65C@2 microprocessor. This programming language is 
called “65C@2 assembly language.” 


There are two steps involved in developing an assembly-language program. 
First, a source.code for the program must be entered that defines the program 
in a human-readable form using symbolic labels for addresses and data, 
special three-character mnemonics for the permitted 65C@2 instructions, and 
special symbols to indicate the addressing modes used by the instructions. 
(See Chapter 2 for a detailed discussion of 65C@2 instructions and addressing 
modes.) 


A typical line of source code looks something like this: 
LABEL LDA (€$28),Y ;This is a comment 


and is made up of four distinct fields. The first field is the label field and it 
holds the symbolic name (if any) for the current location within the program. 
The next field is the instruction field and it holds the three-character mne- 
monic for the 65C@2 instruction (“LDA” in the example). It is immediately 
followed by the operand field, which holds the addressing mode used by the 
instruction, that is, information relating to the method the instruction is to 
use to access the data or memory location on which it is to act, the actual 
address or data itself, or an expression that evaluates to that address or data 
(“‘($28),Y” in the example). The last field is the comment field and is used for 
documenting the program. Each field is separated from the other by at least 
one blank space; in addition, most assemblers require comments to be pre- 
ceded by a semicolon. 


The second step is to interpret or ‘“‘assemble’’ the program source code using 
a 65C@2 assembler. This is done in order to produce a file that contains the 
bytes defined by the program in a format that the 65C@2 can directly execute 
(the “object code” or “machine language’’). 


The assembly-language programs presented in this book were all entered 
and assembled using the Merlin Pro assembler published by Roger Wagner 
Publishing, Inc. (10761 Woodside Avenue, Suite E, Santee, California 92071). 
If you want to modify and reassemble the programs presented in this book 
and you are not using Merlin Pro, then you will likely have to make several 
changes to the program source codes to account for any differences in syntax 
and command structure. Differences usually arise in the area of ‘‘pseudo- 
instructions”; these are assembler-specific commands that appear in the 65C02 
instruction field of a line of source code, but that represent commands to the 
assembler rather than 65C@2 instructions. They can be used to place data 
bytes at specific locations within the program (DFB, DS, and ASC), to define 
symbolic labels (EQU), to indicate the starting address of the program (ORG), 
and for several other purposes. 


Here are descriptions of some of Merlin Pro’s more commonly used 
pseudo-opcodes: 
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DFB—Define a byte of data 

DS—Define a data space 

ASC—Define an ASCII string 

EQU—Equate a symbolic label to a number or a memory location 
ORG—Specify origin (starting address) of object code 


Some of the more popular assemblers available for the //c are listed in the 
references at the end of Chapter 2. 


Running Assembly-Language Programs 


To run an assembly-language program, two steps must take place. The first 
step is obvious: the program must be loaded into memory. This can be done 
by storing the bytes that make up the programs into the appropriate area of 
memory by using Applesoft POKE statements or by using the system monitor 
STORE command. (See Chapter 3.) The easier method, however, is to load it 
from the binary file on diskette in which it is contained (“BIN” is displayed 
to the right of a binary file's name when a diskette is CATALOGued) by using 
the ProDOS BLOAD command. The BLOAD.command must be entered while 
you are in Applesoft and is of the form: 


BLOAD FILENAME ,Aaddr 


where ‘‘FILENAME” represents the name of the binary program and ‘‘addr”’ 
represents the memory location at which it is to be loaded, in hexadecimal 
(if preceded by ‘‘$’’) or decimal notation. The ‘‘,Aaddr’”’ suffix can be omitted 
if you wish; if it is, then the file will be loaded into memory at the same 
position it was in when the BSAVE command was used to save it to diskette. 


The second step is to actually run the program. This can be done by using 
the Applesoft CALL command, which is of the form 


CALL start 


where “‘start’’ represents the decimal starting address of the program. For 
example, to run a program that begins at location $300 (768 decimal), you 
would enter the command CALL 768. The alternative way of starting the 
program is to use the system monitor’s GO command. (See Chapter 3.) This 
can be done by entering the system monitor from Applesoft using a CALL — 
151 command and then, for a program beginning at location $300, entering 
the command “300G”’. 


Some of the programs in this book will not operate properly if they are 
loaded and called in this way (they will be specifically noted). Instead, the 
ProDOS BRUN command must be used to load and execute them directly 
from diskette. This command can be entered as follows: 


BRUN FILENAME 
where “FILENAME” represents the name of the binary program. When the 
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BRUN command is used, the program will be loaded into memory at the 
location from which it was saved to diskette using the ProDOS BSAVE com- 
mand. To save a copy of a binary program that you have already entered into 
memory to a diskette, enter the command: 


BSAVE FILENAME ,Aaddr,bLnum 


where “‘addr” represents the starting address of the program and ‘‘num”’ 
represents the number of bytes in the program, or the command: 
BSAVE FILENAME ,Aaddr1 ,Eaddr2 


where “‘addri” and “addr2” represent the starting and ending addresses, 
respectively, of the program. 


Appendix VI 


Periodicals of Interest 


The following magazines are excellent sources of information on the Apple 
//c (and related products). The address given for each magazine is that of the 
subscription department, which is not necessarily the same as the editorial 
department. 


1. A+, The Independent Guide for Apple Computing 
Price: $24 .97/year ($36.97 in Canada) 
Address: P.O. Box 2965 

Boulder, Colorado 


80321 
2. Apple Assembly Line 
Price: $18/year ($21 in Canada) 


Address: P.O. Box 280300 
Dallas, Texas 


75228 
3. Apple Orchard 
Price: $24.00/year ($30.00 in Canada) 


Address: P.O. Box 6502 
Cupertino, California 


95015 
4. Call -A.P.P.L.E. 
Price: $21.00/year ($36.00 in Canada) 


Address: 290 S.W. 43rd 
Renton, Washington 
98055 
5. inCider 
Price: $25.00/year ($27.97 in Canada) 
Address: P.O. Box 911 
Farmingdale, New York 


11737 
6. Nibble, The Reference for Apple Computing 
Price: $26.95/year ($39.95 in Canada) 


Address: 45 Winthrop Street 
Concord, Massachusetts 
01742 


355 


Index 


— (dash) 123 

& (ampersand) 95 

/RAM 121 

6502 2, 11 

65CQ@2 2, 11-43 
address space 12, 38-41 
addressing modes 27-33 
cycle time 13 
I/O handling 33-34 
instruction set 13—20 
interrupts 34—38 
registers 21-27 
stack 12-13, 26—27, 38 
stack pointer 13, 26—27 
status flags 23-26 
zero page 12-13, 38 

6551 ACIA 299, 303-310 
interrupt handling 318-324 

80/40 switch 157, 185 


8@COL switches 177, 188, 192, 194, 


211, 212, 222 
8Q@STORE switches 192, 194, 208, 
212, 216, 239-240, 242, 
250-251, 316 
ABS 102 
ACIABUF 319, 321 
access code 130 
accumulator 21-22 
addressing modes 27-33 
absolute 29-30 
absolute indexed 32 
absolute indexed indirect 33 
absolute indirect 33 
accumulator 30 
immediate 28-29 
implied 30 
indirect indexed 31 
relative 32 


zero-page indexed indirect 30-31 


zero-page indirect 31 
AKD 160-161, 168-173 
ALTCHARSET switches 194-196 
ALTZP switches 234-235, 236-239 
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alternative character set 194-196 
ampersand command 95 
animation 220-221 
any-key-down switch (see ‘““AKD”) 
APPEND 125 
Apple I 2 
Apple II 

announcement 3 

clones 5 

patent 1 
Apple II Plus 3, 4 
Apple //c 

announcement 6 

back panel 7-8 
Apple //e 5 
Apple /// 4-5 
Applesoft 3, 4, 67-113 

linking to assembly language 

94-97 

memory map 68-72 

source code 68 

tokenization 72—77 

variables 72 
argument register (ARG) 97, 104 
arithmetic 

binary 24, 25-26 

decimal 24, 25-26 
Arkley, John 4 
array variables 83-85 
ARYTAB 71, 72, 78, 82-83 
ASCII codes 141-145 

negative and positive 141 
assembler 

formats 49-51 
ATN 102 
Auricchio, Rick 4, 5 
auto-repeat 168-173 
AUXMOVE 241-244, 250 
bank-switched RAM 41, 230—236 
bank switching 229 
BASCALC 63, 190 
BASIC.SYSTEM 116 

commands 121-126 
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BASL 190 

Baudot code 141 

Baum, Allen 2 

Beernink, Ernie 6—7 

BLOAD command 51, 123 

blocks 116 

break instruction (BRK) 34, 37-38 

BRK (see “break instruction’) 

Broedner, Walt 5 

BRUN 123, 156 

BSAVE 123 

BYE 125 

C3COUTI1 199-200, 203-205 

C3KEYIN 145, 148, 152 

CALL 95 

CAT 122 

CATALOG 122 

CH 146, 201 

CHAIN 125 

character input subroutines 
145-150 

character output subroutines 
199—201 

CHARGET 91-93, 97, 98 

CHARGOT 98 

CHKCOM 102, 105, 108, 110 

CLAMPMOUSE 279 

CLEARMOUSE 279, 280 

CLOSE 125 

CLREOL 63 

CLREOP 63 

CLRSCR 215 

CLRTOP 215 

co-resident programs 245-253 

COLD 103 

COLOR 214 

COLOR= 213 

colors 

high-resolution 219-220, 223 
low-resolution 209, 212~—213 

communications port 313-314 

CONINT 99, 110 

COS 102 


CSW 153, 199-200, 205-206 
CURSOR 148, 153 
CV 146, 201 

cycle time 15, 258 
data bit 301-302 
data format 301-303 
DELETE 123 


DHIRES switches 208, 211, 216, 


222 

Disk ITI 3-4, 115 
directories 119-121 

format of 127—130 
directory file entry 129 
directory header 128 
disk drive 115 

booting 115 

external 115 
diskettes 

formatting 116 
display attributes 194-196 
DISVBL 285 
DISXY 285 
DOCTL 201 
DOS 3.3 4 
DRAW 224, 226 
Dvorak keyboard 157 
EBCDIC codes 141 
effective address 28 
ENBXY 285 
ENVBL 285 
ERRFLAG 102, 103 
ERROR 102 
escape sequences 148-150 
ESCRDKEY 145, 150 
EXEC 124 
EXP 102 
EXTINT2 323 
FADD 100 
FACLO 99, 103 
FDIV 100 
filenames 118-121 
file types 130 
flags (see “status flags’’) 


COUT 65, 199, 203-205 flash video 194-196, 203-205 
COUT! 65, 185, 199-200, 203-205 floating point accumulator (FAC) 


CR 63 96-97, 99, 100, 101, 104, 110 
CREATE 122 FLUSH 125 


FMULT 100 
FNDLIN 98 
FOUT 101 
FRE 125 
FRESPC 100, 101, 103 
FRETOP 71, 72, 79, 81-82, 100, 101 
FRMEVL 99, 101 
FRMNUM 99, 108 
FSUB 100 
functions 82 
FXOEDGE 285 
FYQ@EDGE 285 
game controller 265, 288-293 
GARBAGE 101 
garbage collection 82, 101, 125 
GBASCALC 215 
GBASL 214 
GETADR 100, 110 
GETARYPT 98 
GETBUEFR 117-118 
GETBYT 99 
GETLN 64, 145, 150-152 
GETSPACE 100 
GIVAYF 99, 110 
GOTKEY 148, 154 
GR 213 
H2 214 
HCOLOR= 224 
HGR 224, 226 
HGR2 224, 226 
HHORIZ 225 
high-resolution graphics mode 
214-227 
animation 220-221 
commands 223-225 
double-width 221-223 
double-width colors 223 
double-width memory mapping 
222-223 
single-width colors 219-220 
single-width memory mapping 
217-218 
turning on double-width 
turning on single-width 215-217 
HIMEM: 71, 72 
and ProDOS 117-118 
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HIRES switches 208, 210, 222, 
239-240 
HLIN (high-res) 226 
HLIN (low-res) 213 
HLINE 215 
HMASK 225 
Holt, Rod 1 
HOME 63 
HOMEMOUSE 280 
HPAG 225 
HPLOT 224, 226 
Huston, J.R. 4, 6—7 
HVERT 225 
IN# 125, 152-153, 155—157 
index registers 22—23 
INITMOUSE 280 
input buffer 39, 69 
Input/Output memory 41-42 
input link 147, 152-153 
effect of ProDOS 154-157 
ProDOS link 156 
instruction pointer (see 
“program counter’) 
instructions (65C@2) 13-20 
Integer BASIC 2, 3 
integer numbers 85-86 
interrupt requests (IRQ) 34, 36-37 
interrupts 24—25, 34-38 
external 323-324 
mouse 267-268, 280 
serial interface 318—324 
inverse video 194-196, 203-205 
INVFLG 204 
IOUDIS switches 208, 211, 216, 
222, 285 
IRQ (see “interrupt requests’) 
Jobs, Stephen 1-2 
KBD 160-161, 173, 321-323 
KBDSTRB 160-161, 168-173, 323 
key block 127 
keyboard 157-181 
80/40 switch 157 
auto-repeat 168-173 
I/O locations 160-161 
interrupts 321-323 
keyboard switch 157 
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reset key 173-181 
strobe 160-161 
keyboard input 148-150 
modifying 153-154, 164-168 
KEYIN 64, 145, 148, 152-154, 185 
keywords 74-77 
KSW 147, 152-153, 164 
Language Card 4 
line input subroutines 150—152 
LINGET 102 
links 60, 147 
LINNUM 98, 100, 102, 103, 110 
LINPRT 100 
Lisa 5 
LOAD 124 
LOCK 123, 130 
LOG 102 
LOMEM: 71 
low-resolution graphics mode 
207-214 
commands 213-214 
double-width 210-213 
double-width colors 212—213 
double-width memory mapping 
212 
single-width colors 209 
single-width memory mapping 
209 
turning on double-width 
210-211 
turning on single-width 
208-209 
LOWTR 98, 103 
machine language interface 
132-134 
Macintosh 6 
Markkula, Mike 2, 6 
MASK 214 
memory map 
auxiliary RAM memory 41, 
236-245 
bank-switched RAM 41 
Input/Output memory 41—42 
main RAM memory 38-41 
ROM memory 42 
memory-mapped I/O 33-34, 


183-184 
MEMSIZ 71, 72, 81 
Merlin Pro assembler 9-10, 49 
Microsoft 3, 67 
MIXED switches 208-209, 210, 
216, 222 
MLI (see ‘‘machine language 
interface’’) 
MON 45-46 
MONZ 45—46, 65 
mouse 265-288 
Applesoft control 269-273 
assembly language control 
273-280 
comparison with //e mouse 
275-278 
how it works 266—267 
joystick emulation 280-281 
operating modes 267—268 
screen hole usage 274 
MouseText 183, 196-199 
MOUSEXINT 288 
MOUSEYINT 288 
MOUSTAT 268, 278, 279, 280 
MOUX1 288 
MOUY! 288 
MOVESTR 100, 101 
musical notes 255-259 
NEWESC 148 | 
NMI (see ‘‘non-maskable 
interrupts ’’) 
non-maskable interrupts (NMI) 34 
OFFBSR1 232 
OFFBSR2 232 
OLDRST 45-46 
opcode 27—28 
OPEN 124 
OPEN-APPLE key 159, 173-174, 
295, 322 
OURCH 201 
OURCV 201 
output link 153, 199-200, 205-207 
effect of ProDOS 206-207 
PAGE2 switches 192~—194, 208, 212, 
216, 239-240 
page 3 vectors 118 


page of memory (definition) 12 

parity bit 302 

Pascal 4, 230 

pathnames 118-121 

PDL inputs 289-293 

photoresistor 292—293 

pixels 214, 216 

PLOT (high-res) 215 

PLOT (low-res) 213 

port assignments 9 

port selection 60 

POSITION 125 

POSMOUSE 279 

PR# 125, 205, 207 

PRBYTE 64 

PREFIX 120-121, 123 

PRGEND 71 

PREAD 63, 285, 290 

prefix 120-121 

primary character set 194-196 

printer port 311-313 

PRINTYX 62, 63 

PRNTFAC 100, 108 

processor Status register 23 

ProDOS 115-140 
announcement 6 
memory map 116-118 

program counter 27 

prompt symbols 151 

PTRIG 288, 289-290, 292 

PTRGET 98, 104-108 

push buttons 293-296 

PWREDUP 174-175 

Quinn, Peter 5 

RAMRD switches 237, 239-240, 

250-251 


RAMWRT switches 237, 239-240, 


250-251 
RD63 288 
RD8O0SW 185 
RDBANK2 232-234 
RDCHAR 64, 145, 150 
RDKEY 64, 145-150, 152 
RDLCRAM 232-234 
RDVBLMSK 288 
RDXOEDGE 288 
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RDYOEDGE 288 

RDXYMSK 288 

READ 125 

READBSRI1 232 

READBSR2 232 

READMOUSE 268, 278, 279 

real numbers 87-89 

registers 21-27 
accumulator 21—22 
index (X and Y) 22-23 
processor status 23 
program counter 27 

RENAME 123 

RESET 174 

reset interrupt 34, 36, 173-181 
trapping reset 174-181 

RESTORE 126 

ROM memory 42 

ROT 225 

ROT = 224 


RS-232-C standard 300, 304-305 


RSTXY 288 

RUN 124 

RX@EDGE 285 

RYOEDGE 285 

sapling file 131-132 

SAVE 124 

SCALE 225 

SCALE= 224 

SCRN (high-res) 215 

SCRN (low-res) 213 

Sculley, John 6 

seedling file 131 

serial interface 299-303 
configuration 310 

SERVEMOUSE 279, 280 

SETCOL 215 

SETHCOL 226 

SETMOUSE 278 

Shepardson, Bob 4 

Sholes keyboard 157 

SHOWCUR 148, 154 

simple variables 78-83 

SIN 102 

SOFTEV 174-175 

SOLID-APPLE key 159, 295 
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speaker 255-263 
V/O location 255 

SOR 102 

stack 12—13, 26—27, 38, 69 

stack pointer 13, 26—27 

start bit 301 

status flags 23-26 
break 25 
carry 23-24 
decimal mode 25 
interrupt disable 24-25 
negative 26 
overflow 25-26 
zero 24 

Stearns, Bryan 5 

stop bit 302 

STORCH 200 

STORE 126 

STORY 154 

STREND 71, 72, 78, 82, 85 

STROUT 101 

STRPRT 101 

“Sweet 16” 2 

system monitor 45-65 
ADD command 57 
BASIC command 57 
command syntax 46, 61 
CONTINUE BASIC command 

57-58 

DISPLAY command 46, 48—49 
entry points 45—46 
EXAMINE command 53—54, 62 
GO command 54-55, 62 
INVERSE command 57 
KEYBOARD command 59-61 
LIST command 55—56 
MOVE command 51-53 
NORMAL command 57 
PRINTER command 59-61 
STORE command 49-51 
subroutines 61-65 
SUBTRACT command 57 
USER command 58-59 
VERIFY command 53 
TAN 102 
terminal mode 314-316 


text mode 184—207 
memory mapping 188-194 
turning it on 185-188 
TEXT switches 188, 208, 210, 216, 
222 
thermistor 292 
tree file 131-132 
TRKEY 322 
TWKEY 322 
two's complement 85-86 
TXTPTR 90-94, 98, 98, 99, 102, 
103, 104-108 
TXTTAB 790, 73, 194 
TYPHED 322, 323 
UNLOCK 123, 130 
UPDATE 154 
USR 96-97, 104 
V2 214 
variables 72, 77—85 
evaluating 108 
locating 104-108 
VARPNT 98, 103, 104-108 
VARTAB 71, 72, 78 
VBL interrupt 221, 267, 268, 278 
VBLINT 288 
VERIFY 123 
vertical blanking interrupt (see 
“VBL interrupt’) 
VFACTV 176-177 
video RAM 
auxiliary memory 191-192 
high-resolution pages 40—41, 72, 
215-218, 222—223, 236 
low-resolution pages 208-209, 
212 
text pages 40, 69, 189-194, 236 
VIDOUT 200 
VIDOUT!1 201 
VIDWAIT 200 
VisiCalc 4 
VLIN 213 
VLINE 215 
VMODE 148, 150 
volume bit map 126 
VTAB 63 
WAIT 64 


WARM 103 
Wigginton, Randy 3, 4 
Williams, Rich 6—7 
windows 202—203 
WNDBTM 203 
WNDLFT 203 
WNDTOP 203 
WNDWDTH 203 
Wozniak, Stephen 1-2 
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WRITE 125 
WRITEBSR1 232 
WRITEBSR2 232 
XDRAW 224, 226 
XFER 244-245 
XRDSER 320 
zero page 12-13, 38, 69 
free space chart 41 
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